Authentication

Zeplin API uses a token based authentication mechanism to enable Zeplin apps to access Zeplin API on behalf of a Zeplin user. When a Zeplin user authorizes a Zeplin app, the application is given a token that can be used to make requests to Zeplin API on behalf of the user.

Zeplin apps use OAuth 2.0 to establish a connection between a Zeplin user and app's access to the API on behalf of the user. Zeplin API supports authorization code grant to generate tokens.

Authorizing a Zeplin app

There are 3 steps to authorize a Zeplin app.

  • Users are redirected to Zeplin's web app to authenticate themselves and authorize the Zeplin app.
  • Users are redirected back to your redirect URI by Zeplin with a code parameter.
  • Your app requests an access token using the code parameter.

Redirecting users to Zeplin web app to authorize the Zeplin app

Make a GET request to https://api.zeplin.dev/v1/oauth/authorize in a browser window with the following parameters:

  • client_id (required): Identifier of your Zeplin app
  • redirect_uri (required): URL of your application where users will be redirected to after authorization
  • response_type (required): Always code
  • state (optional): An unguessable random string used to protect against cross-site request forgery attacks
  • code_challenge (optional): A PKCE code challenge derived from the code verifier, to be verified against later
  • code_challenge_method (optional): PKCE code verifier transformation method

The redirect_uri you specified in the request must exactly match one of the whitelisted redirect URIs configured for your app.

Zeplin API supports PKCE extension for OAuth 2.0 to securely generate tokens for public clients. Since using client_secret of your Zeplin app inside a public client would be insecure, PKCE authorization flow allows you to avoid using it. The code_challenge and code_challenge_method parameters are used to verify token requests against their code_verifier parameters.

Handling redirection

If the user authorizes your app, Zeplin redirects them back to the redirect URI you provided, including a code parameter and the state parameter you provided. You then exchange the code parameter for an access token and a refresh token.

Make a POST request to https://api.zeplin.dev/v1/oauth/token endpoint with this request body:

  • grant_type (required): Always authorization_code
  • code (required): code parameter you got from Zeplin
  • redirect_uri (required): URL of your application where users redirected to after authorization
  • client_id (required): Identifier of your Zeplin app
  • client_secret (optional): Client secret of your Zeplin app
  • code_verifier (optional): Code verifier used to generate the code_challenge using code_challenge_method

The code parameter cannot be used more than once and expires after 10 minutes.

The client_secret parameter is required when code parameter is created without a code_challenge.

The token response should look like so:

{
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjbGllbnRfaWQiOiI1ZDkyMDQ4ZTdkNjFlYjVkODYzNGY0OWUiLCJzY29wZSI6IiIsImlhdCI6MTU2OTg1MDUxMSwiZXhwIjo4Nzk2OTg1MDUxMSwic3ViIjoiNWQ5MjA0OGU3ZDYxZWI1ZDg2MzRmNDlmIiwianRpIjoiNzZjMWQ3YjAtYWUzOS00N2ExLTg2MDYtNTNkZjYyOGYxMmE0In0.YhIC_QdOo3JmX-fY1LLxXgn3BAQR8-W-ptbVXiIlOGw",
    "expires_in": 3600,
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjbGllbnRfaWQiOiI1ZDkyMDQ4ZTdkNjFlYjVkODYzNGY0OWUiLCJzY29wZSI6IiIsImlhdCI6MTU2OTg1MDUxMSwiZXhwIjo4NjU1Njk4NTA1MTEsInN1YiI6IjVkOTIwNDhlN2Q2MWViNWQ4NjM0ZjQ5ZiIsImp0aSI6ImQ2NWI5NDI1LTkxMTUtNDhmYy1hODg2LTJjYTczNmZmNjg0ZSJ9.AFd8Zn8-sl1SVvNIzAruMnTFlrohSrz2BQClNBPSLlY",
    "refresh_expires_in": 5184000,
    "token_type": "bearer"
}

Now you can use the access token to request resources, by setting the Authorization header as Bearer {access_token}.

Refreshing an access token

By default, the lifetime of an access token is about an hour and the lifetime of a refresh token is around two months, which is much longer than that of the access token. Once the access token you're using expires, or is about to expire, you can request a new access token using the refresh token. This avoids you to go through the same authorization flow that requires user interaction.

Make a POST request to https://api.zeplin.dev/v1/oauth/token endpoint with the following parameters:

  • grant_type (required): Always refresh_token
  • refresh_token (required): refresh_token parameter you got from Zeplin, along with the access token
  • client_id (required): Identifier of your Zeplin app
  • client_secret (optional): Client secret of your Zeplin app
  • code_verifier (optional): Code verifier used to generate the code_challenge using code_challenge_method

The client_secret parameter is required when code parameter is created without a code_challenge.

The refresh token response should be similar, like so:

{
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjbGllbnRfaWQiOiI1ZDkyMDQ4ZTdkNjFlYjVkODYzNGY0OWUiLCJzY29wZSI6IiIsImlhdCI6MTU2OTg1MDUxMSwiZXhwIjo4Nzk2OTg1MDUxMSwic3ViIjoiNWQ5MjA0OGU3ZDYxZWI1ZDg2MzRmNDlmIiwianRpIjoiNzZjMWQ3YjAtYWUzOS00N2ExLTg2MDYtNTNkZjYyOGYxMmE0In0.YhIC_QdOo3JmX-fY1LLxXgn3BAQR8-W-ptbVXiIlOGw",
    "expires_in": 3600,
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjbGllbnRfaWQiOiI1ZDkyMDQ4ZTdkNjFlYjVkODYzNGY0OWUiLCJzY29wZSI6IiIsImlhdCI6MTU2OTg1MDUxMSwiZXhwIjo4NjU1Njk4NTA1MTEsInN1YiI6IjVkOTIwNDhlN2Q2MWViNWQ4NjM0ZjQ5ZiIsImp0aSI6ImQ2NWI5NDI1LTkxMTUtNDhmYy1hODg2LTJjYTczNmZmNjg0ZSJ9.AFd8Zn8-sl1SVvNIzAruMnTFlrohSrz2BQClNBPSLlY",
    "refresh_expires_in": 5184000,
    "token_type": "bearer"
}

Note that after using a refresh token to get a new access token, the refresh token you use immediately expires. You can then start using the new refresh token you get in the response.

If an access token is refreshed without submitting the client_secret parameter, the new refresh token uses the same expiration date with the previous refresh token.