openapi: 3.0.2
info:
  title: Zeplin Authorization API
  description: Access your resources in Zeplin
  version: 1.38.0
  contact:
    name: Zeplin
    url: https://zeplin.io
    email: support@zeplin.io
servers:
- url: https://api.zeplin.dev
security:
- PersonalAccessToken: []
- OAuth2: []
tags:
- name: Authorization
paths:
  /v1/oauth/authorize:
    get:
      tags:
      - Authorization
      summary: Authorization endpoint
      description: Users are redirected to web app to authenticate themselves and authorize the app with `client_id` to act on behalf of themselves.
      operationId: OAuthAuthorize
      security: []
      x-readme:
        code-samples:
        - language: node
          name: sdk
          code: "import { ZeplinApi }  from \"@zeplin/sdk\";\n\nconst zeplin = new ZeplinApi();\n\nconst redirectUrl = zeplin.authorization.getAuthorizationUrl({\n  clientId: \"YOUR_CLIENT_ID\",\n  redirectUri: \"YOUR_REDIRECT_URI\",\n  state: \"YOUR_STATE\", // Optional\n  codeChallenge: \"YOUR_CODE_CHALLENGE\", // Optional\n  codeChallengeMethod: \"S256\" // or \"plain\" (optional)\n});\n"
      parameters:
      - name: response_type
        in: query
        description: Only `code` flow is supported
        required: true
        schema:
          type: string
      - name: client_id
        in: query
        description: Identifier of the Zeplin app requesting user authentication
        required: true
        schema:
          type: string
      - name: redirect_uri
        in: query
        description: User is redirected to this endpoint after authorization
        required: true
        schema:
          type: string
      - name: state
        in: query
        description: RECOMMENDED. An opaque value used by the client to maintain state between the request and callback.
        schema:
          type: string
      - name: code_challenge
        in: query
        description: RECOMMENDED. A PKCE code challenge derived from the code verifier, to be verified against later.
        schema:
          type: string
      - name: code_challenge_method
        in: query
        description: RECOMMENDED. PKCE code verifier transformation method.
        schema:
          type: string
          enum:
          - plain
          - S256
          default: S256
      responses:
        '302':
          description: User is redirected to web app for authorization
  /v1/oauth/token:
    post:
      tags:
      - Authorization
      summary: Access token endpoint
      description: If `grant_type` is given as `authorization_code`; handles code flow. If `grant_type` is given as `refresh_token` handles refresh token flow.
      operationId: OAuthPostToken
      security: []
      x-readme:
        code-samples:
        - language: node
          name: sdk
          code: "import { \n  ZeplinApi,\n  Configuration\n}  from \"@zeplin/sdk\";\n\nlet zeplin = new ZeplinApi();\n\nconst createTokenResponse = await zeplin.authorization.createToken({\n  code: \"CODE_FROM_AUTHORIZATION_CODE_FLOW\",\n  clientId: \"YOUR_CLIENT_ID\",\n  clientSecret: \"YOUR_CLIENT_SECRET\",\n  redirectUri: \"YOUR_REDIRECT_URI\",\n  codeVerifier: \"YOUR_CODE_VERIFIER\", // If PKCE is used\n});\n\nzeplin = new ZeplinApi(\n  new Configuration({ \n    accessToken: createTokenResponse.data.access_token \n  })\n);\n\n// You can now use `zeplin` to make requests to the Zeplin API\n\n// When a token expires, you can refresh it with the `refresh_token`\n\nconst refreshTokenResponse = await zeplin.authorization.refreshToken({\n  refreshToken: createTokenResponse.data.refresh_token, // or refresh_token from previous refreshToken response\n  clientId: \"YOUR_CLIENT_ID\",\n  clientSecret: \"YOUR_CLIENT_SECRET\",\n  codeVerifier: \"YOUR_CODE_VERIFIER\", // If PKCE is used\n});\n\nzeplin = new ZeplinApi(\n  new Configuration({ \n     accessToken: refreshTokenResponse.data.access_token \n  })\n);\n"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TokenCreateBody'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
              examples:
                response:
                  $ref: '#/components/examples/tokenResponse'
        '400':
          description: Bad request response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Code is expired:
                  value:
                    message: invalid_grant
                    detail: Provided `code` is expired
                Code is malformed:
                  value:
                    message: invalid_grant
                    detail: Provided `code` is malformed
                Code is used before:
                  value:
                    message: invalid_grant
                    detail: Provided `code` is used before
                Code is not for client:
                  value:
                    message: invalid_grant
                    detail: Provided `code` is not usable for the provided `client_id`
                Refresh token is not for client:
                  value:
                    message: invalid_grant
                    detail: Provided `refresh_token` is not usable for the provided `client_id`
                Redirect URI is not for application:
                  value:
                    message: invalid_grant
                    detail: Provided `redirect_uri` must be whitelisted for the application
                Client credentials are incorrect:
                  value:
                    message: invalid_client
                    detail: Provided `client_id` or `client_secret` are incorrect
                Refresh token with increased scope:
                  value:
                    message: invalid_scope
                    detail: Refresh token cannot be used with increased scope
                Refresh token is expired:
                  value:
                    message: invalid_grant
                    detail: Provided `refresh_token` is expired
                Refresh token is malformed:
                  value:
                    message: invalid_grant
                    detail: Provided `refresh_token` is malformed
                Code challenge is invalid:
                  value:
                    message: invalid_grant
                    detail: Provided `code_challenge` is invalid
                Code challenge method is invalid:
                  value:
                    message: invalid_grant
                    detail: Provided `code_challenge_method` is invalid
                Code verifier is required:
                  value:
                    message: invalid_grant
                    detail: '`code_verifier` is required'
                Code verifier is incorrect:
                  value:
                    message: invalid_grant
                    detail: Provided `code_verifier` is incorrect
components:
  examples:
    error:
      summary: Error
      value:
        message: Project is not found
    tokenResponse:
      summary: Token Response
      value:
        access_token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjbGllbnRfaWQiOiI1ZDkyMDQ4ZTdkNjFlYjVkODYzNGY0OWUiLCJzY29wZSI6IiIsImlhdCI6MTU2OTg1MDUxMSwiZXhwIjo4Nzk2OTg1MDUxMSwic3ViIjoiNWQ5MjA0OGU3ZDYxZWI1ZDg2MzRmNDlmIiwianRpIjoiNzZjMWQ3YjAtYWUzOS00N2ExLTg2MDYtNTNkZjYyOGYxMmE0In0.YhIC_QdOo3JmX-fY1LLxXgn3BAQR8-W-ptbVXiIlOGw
        expires_in: 86400000
        refresh_token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjbGllbnRfaWQiOiI1ZDkyMDQ4ZTdkNjFlYjVkODYzNGY0OWUiLCJzY29wZSI6IiIsImlhdCI6MTU2OTg1MDUxMSwiZXhwIjo4NjU1Njk4NTA1MTEsInN1YiI6IjVkOTIwNDhlN2Q2MWViNWQ4NjM0ZjQ5ZiIsImp0aSI6ImQ2NWI5NDI1LTkxMTUtNDhmYy1hODg2LTJjYTczNmZmNjg0ZSJ9.AFd8Zn8-sl1SVvNIzAruMnTFlrohSrz2BQClNBPSLlY
        refresh_expires_in: 864000000
        token_type: bearer
  schemas:
    TokenResponse:
      title: Token Response
      type: object
      required:
      - access_token
      - expires_in
      - refresh_token
      - refresh_expires_in
      - token_type
      properties:
        access_token:
          type: string
          description: Access token that allows you to make requests to the API on behalf of a user
        expires_in:
          type: number
          description: Access token's lifetime in seconds
        refresh_token:
          type: string
          description: Refresh token that allows you to obtain access tokens
        refresh_expires_in:
          type: number
          description: Refresh token's lifetime in seconds
        token_type:
          type: string
          description: Type of the token returned
      example:
        $ref: '#/components/examples/tokenResponse'
    TokenCreateRefreshTokenBody:
      title: Refresh token flow
      type: object
      required:
      - grant_type
      - refresh_token
      - client_id
      properties:
        grant_type:
          type: string
          enum:
          - refresh_token
        refresh_token:
          type: string
          description: Applies when `grant_type` is `refresh_token`. The `refresh_token` you obtained while generating the access token in the first place
        client_id:
          type: string
          description: The `client_id` of your Zeplin app
        client_secret:
          type: string
          description: "The `client_secret` of your Zeplin app\n\n**Note**: `client_secret` is required for `code` values obtained without using a PKCE `code_challenge` value.\n\n**Warning**: `client_secret` property should only be used in a server-side application. \nIf your Zeplin app is a public client, you should use PKCE authorization flow.\n"
        code_verifier:
          type: string
          description: A cryptographically random string that is used to correlate the authorization request to the token request
    ErrorResponse:
      title: Error Response
      type: object
      required:
      - message
      properties:
        message:
          type: string
          description: A user readable descriptive message for the error
        detail:
          type: string
          description: A detailed message describing the error
        code:
          type: string
          description: The unique code for the error
      example:
        $ref: '#/components/examples/error'
    TokenCreateAuthorizationCodeBody:
      title: Authorization code flow
      type: object
      required:
      - grant_type
      - code
      - redirect_uri
      - client_id
      properties:
        grant_type:
          type: string
          enum:
          - authorization_code
        code:
          type: string
          description: Applies when `grant_type` is `authorization_code`. The `code` obtained after `authorization` request
        redirect_uri:
          type: string
          description: The URL where users will be redirected after authorization
        client_id:
          type: string
          description: The `client_id` of your Zeplin app
        client_secret:
          type: string
          description: "The `client_secret` of your Zeplin app\n\n**Note**: `client_secret` is required for `code` values obtained without using a PKCE `code_challenge` value.\n\n**Warning**: `client_secret` property should only be used in a server-side application. \nIf your Zeplin app is a public client, you should use PKCE authorization flow.\n"
        code_verifier:
          type: string
          description: A cryptographically random string that is used to correlate the authorization request to the token request
    TokenCreateBody:
      title: Token Create Body
      discriminator:
        propertyName: grant_type
        mapping:
          authorization_code: '#/components/schemas/TokenCreateAuthorizationCodeBody'
          refresh_token: '#/components/schemas/TokenCreateRefreshTokenBody'
      oneOf:
      - $ref: '#/components/schemas/TokenCreateAuthorizationCodeBody'
      - $ref: '#/components/schemas/TokenCreateRefreshTokenBody'
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: /v1/oauth/authorize
          tokenUrl: /v1/oauth/token
          refreshUrl: /v1/oauth/token
          scopes: {}
    PersonalAccessToken:
      type: http
      scheme: bearer
      bearerFormat: JWT