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.