---
openapi: 3.0.3
info:
  title: Snyk OAuth2 API
  version: 1.0.0
servers:
  - url: https://api.snyk.io/oauth2
    description: Snyk OAuth2 API
tags:
  - name: oauth2
    description: oauth2
x-hideTryItPanel: true
x-codeSamples: true
paths:
  /token:
    post:
      summary: Request an access token
      description:
        Allows the client application to exchange the authorization code
        received from the authorization server for an access token.
      tags: [oauth2]
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              oneOf:
                - $ref: "#/components/schemas/AuthCode"
                - $ref: "#/components/schemas/RefreshToken"
                - $ref: "#/components/schemas/ClientCredentials"
              discriminator:
                propertyName: grant_type
      responses:
        "200":
          description: Successful token request
          content:
            application/json:
              schema:
                type: object
                properties:
                  access_token:
                    description: The access token granted to the client application.
                    type: string
                    example: some_opaque_access_token_string
                  expires_in:
                    description: The number of seconds until the access token expires.
                    type: integer
                    example: 3599
                  refresh_token:
                    description:
                      Refresh token that can be used to obtain a new access
                      token. Will not be granted in `client_credentials` grants.
                    type: string
                    example: some_opaque_refresh_token_string
                  refresh_expires_in:
                    description: The number of seconds until the refresh token expires.
                    type: integer
                    example: 15552000
                  token_type:
                    description: The type of token issued.
                    type: string
                    enum: [bearer]
                    example: bearer
                  scope:
                    description:
                      The space-separated list of scopes granted to the
                      client application.
                    type: string
                    example: org.read org.project.read org.project.snapshot.read
                  bot_id:
                    description: ID of the newly created bot user.
                    type: string
                    format: uuid
                    example: 95233fa3-33cf-4dd3-a6ac-e040985e1a4f
                required: [access_token, expires_in, token_type, scope, bot_id]
        "400":
          $ref: "#/components/responses/InvalidRequest"
        "401":
          $ref: "#/components/responses/Forbidden"
        "403":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/ServerError"
  /revoke:
    post:
      summary: Revoke refresh token
      description:
        Revokes an otherwise valid refresh token so it can't be reused.
        This is used when a refresh token is accidentally, or maliciously, leaked.
      tags: [oauth2]
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                client_id:
                  description: The client ID of the client application.
                  type: string
                  example: 64ae3415-5ccd-49e5-91f0-9101a6793ec2
                client_secret:
                  description: The client secret of the client application.
                  type: string
                  example: super_secret_client_secret
                token:
                  description: The refresh token to be revoked.
                  type: string
                  example: some_opaque_refresh_token_string
              required: [client_id, client_secret, token]
      responses:
        "200":
          description: The token has been revoked, or was invalid.
        "400":
          $ref: "#/components/responses/InvalidRequest"
        "401":
          $ref: "#/components/responses/Forbidden"
        "403":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/ServerError"
components:
  schemas:
    AuthCode:
      type: object
      properties:
        grant_type:
          description:
            The type of grant used in the request. Use `authorization_code`
            to exchange an authorization code for an access token.
          type: string
          enum: [authorization_code]
          example: authorization_code
        code:
          description: The authorization code received from the authorization server.
          type: string
          example: returned_auth_code
        client_id:
          description: The client ID of the client application.
          type: string
          example: 64ae3415-5ccd-49e5-91f0-9101a6793ec2
        client_secret:
          description: The client secret of the client application.
          type: string
          example: super_secret_client_secret
        code_verifier:
          description: The code verifier used to generate the code challenge.
          type: string
          example: your_secure_code_verifier
      required:
        - grant_type
        - code
        - client_id
        - client_secret
        - code_verifier
    RefreshToken:
      type: object
      properties:
        grant_type:
          description:
            The type of grant used in the request. Use `refresh_token`
            to exchange a refresh token for a new access token and refresh token pair.
          type: string
          enum: [refresh_token]
          example: refresh_token
        client_secret:
          description: The client secret of the client application.
          type: string
          example: super_secret_client_secret
        refresh_token:
          description:
            A previously issued refresh token. This token will be consumed
            when it is used here so cannot be reused.
          type: string
          example: some_opaque_refresh_token_string
      required: [grant_type, client_secret, refresh_token]
    ClientCredentials:
      oneOf:
        - $ref: "#/components/schemas/ClientCredentialsSecret"
        - $ref: "#/components/schemas/ClientCredentialsJWT"
      discriminator:
        propertyName: client_assertion_type
    ClientCredentialsBase:
      type: object
      properties:
        grant_type:
          description:
            The type of grant used in the request. Use `client_credentials`
            to exchange credentials for an access token, typically used with Service
            Accounts. Supports either client_secret or private_key_jwt auth.
          type: string
          enum: [client_credentials]
          example: client_credentials
      required: [grant_type]
    ClientCredentialsSecret:
      allOf:
        - $ref: "#/components/schemas/ClientCredentialsBase"
        - type: object
          properties:
            client_id:
              description: The client ID of the client application.
              type: string
              example: 64ae3415-5ccd-49e5-91f0-9101a6793ec2
            client_secret:
              description:
                The client secret of the client application.
              type: string
              example: super_secret_client_secret
          required: [client_id, client_secret]
    ClientCredentialsJWT:
      allOf:
        - $ref: "#/components/schemas/ClientCredentialsBase"
        - type: object
          properties:
            # client_id is optional on this assertion but required with the
            # client secret. Can't express in openapi that without duplicating
            # the field.
            client_id:
              description: The client ID of the client application.
              type: string
              example: 64ae3415-5ccd-49e5-91f0-9101a6793ec2
            client_assertion:
              description:
                "A compact signed JWT containing claims detailed in OIDC Connect\
                \ Core 1.0, section 9.\n\nRequired header claims:\n- kid: KeyID which\
                \ matches a public key in the registered JWKS endpoint.\n\nRequired payload\
                \ claims:\n- sub: client_id of your Service Account.\n- iss: client_id\
                \ of your Service Account.\n- jti: A cryptographically unique value (nonce)\
                \ to prevent replay attacks.\n- aud: Full URL for this token endpoint\
                \ - \"https://api.snyk.io/oauth2/token\".\n- exp: Unix timestamp of when\
                \ the token shouldn't be accepted for processing. We suggest now() + 5\
                \ minutes.\n\nThe JWT must be signed using a private key with RSA256 (RSASSA-PKCS-v1.5\
                \ using SHA-256), and its public key must be exposed on the previously\
                \ registered JWKS endpoint"
              type: string
            client_assertion_type:
              description:
                The method of client_assertion being sent. Only
                "urn:ietf:params:oauth:client-assertion-type:jwt-bearer" is
                supported.
              type: string
              enum: [urn:ietf:params:oauth:client-assertion-type:jwt-bearer]
              example: urn:ietf:params:oauth:client-assertion-type:jwt-bearer
          required: [client_assertion, client_assertion_type]
    OAuthError:
      type: object
      properties:
        error:
          description:
            "An error ID. The full list of possible values can be found
            in the OAuth Extensions Error Registry maintained by IANA: https://www.iana.org/assignments/oauth-parameters/oauth-parameters.xhtml"
          type: string
          example: invalid_request
        error_description:
          description: Human readable description about what happened.
          type: string
          example:
            The request is missing a required parameter, includes an invalid
            parameter value, includes a parameter more than once, or is otherwise
            malformed. Request parameter 'grant_type' is missing
      required: [error, error_description]
  responses:
    InvalidRequest:
      description: Invalid request
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/OAuthError"
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/OAuthError"
    Forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/OAuthError"
    ServerError:
      description: An unexpected server error.