Akoya Token API OpenAPI specification

openapi: 3.1.0
x-stoplight:
  id: p0x6tqjrrxsoi
info:
  title: Akoya Token API v2.2
  description: "Akoya Token APIs for data recipients. Default servers are set to override for the Akoya sandbox environment.\r\n\r\nUpdates:\r\n\r\nNovember 21, 2024\r\n- Added 400 level responses"
  version: '2.2'
  contact:
    name: API Support
    url: 'http://www.akoya.com'
    email: [email protected]
  license:
    name: Akoya Terms of Use
    url: 'https://recipient.ddp.akoya.com/terms-of-use'
servers:
  - url: 'https://sandbox-idp.ddp.akoya.com'
    description: Sandbox IdP server
  - url: 'https://idp.ddp.akoya.com'
    description: IdP server
tags:
  - name: Tokens
    description: Token Management
security:
  - {}
  - BasicAuth: []
paths:
  /token:
    post:
      tags:
        - Tokens
      x-stoplight:
        id: 9fpzy9ocl3yoz
      summary: Token
      description: |
        The token endpoint is used to **obtain** tokens during authorization or to **refresh** tokens without having to go through authorization again. In each successful token response, you will receive a new `id_token` and a new `refresh_token`.

        > ⚠️ Please note!
        >
        > Use the correct schema (detailed below) for the type of token request you're making. The initial token request and the refresh token requests require different security schemas and parameters.

        ## Obtain tokens

        To obtain the initial set of tokens or to reauthorize, you will need the following:

        - `grant_type` must be set to `authorization_code`.
        - `redirect_uri` must be the same as your app's registered `redirect_uri`.
        - `code` is the authorization code from the end-user's authentication flow. See: [Get authorization code](https://docs.akoya.com/reference/get-authorization-code).
        - **Security**: Include Basic Auth in the header of the call. Select "Basic Auth" in Try it and use your `client_id` and `client_secret` as username & password.

        ## Refresh tokens

        Refresh token expiration times are set by the provider.

        - `grant_type` must be set to `refresh_token`.
        - `refresh_token` must be set to the refresh token received in the most recent, previous obtain or refresh token call for your end-user.
        - **Security**: Include your `client_id` and `client_secret` **in the body of the request**. Remove any information from "Basic Auth" (username and password) in Try it. 

        ## Responses

        Token requests return a new set of tokens. If refreshing or reauthorizing tokens, they will replace the tokens from your previous, successful obtain or refresh token call. 

        The `id_token` (JWT) is a short-lived token. It's used as the **bearer token** for data calls. To ensure data calls are secure, the `id_token` must be renewed regularly. To retrieve a new `id_token`, use the refresh token request. [Read more about tokens](https://docs.akoya.com/docs/token-flow).
      operationId: get-token
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              oneOf:
                - $ref: '#/components/schemas/obtainTokenRequest'
                  x-stoplight:
                    id: aanphok0h67du
                - $ref: '#/components/schemas/refreshTokenRequest'
                  x-stoplight:
                    id: u5ut0wnfac2vy
            examples:
              Request body:
                value:
                  grant_type: authorization_code
                  redirect_uri: string
                  code: string
        description: ''
      deprecated: false
      responses:
        '200':
          description: OK
          content:
            application/x-www-form-urlencoded: {}
            application/json:
              schema:
                $ref: '#/components/schemas/tokenResponse'
              examples:
                Successful response:
                  value:
                    token_type: bearer
                    expires_in: 86399
                    refresh_token: ChlnNm5hdWV4ZWN0aWdpdmJvdn...ZXZwbXNpaXh5ZWN6dWE3a21kbjZt
                    id_token: eyJhbGciOiJSUzI1NiIsImtpZCI6IjJ...lAQGaJAsWlA3YdBBaL2ftE-v2g4fctKOug
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
              examples:
                Invalid credentials:
                  value:
                    error: invalid_ client
                    error _description: Invalid client credentials.
                Invalid grant:
                  value:
                    error: invalid _grant
                    error _description: Invalid grant type.
                Missing refresh token:
                  value:
                    error: invalid request
                    error description: No refresh token in request.
                Bad token:
                  value:
                    error: invalid_request
                    error description: Refresh token is invalid or has already been claimed by another client.
                Bad grant type:
                  value:
                    error: invalid _grant
                    error _description: Unsupported grant type.
                Refreshing a revoked token:
                  value:
                    error: token_inactive
                    error_description: 'Token is inactive because it is malformed, expired, or otherwise invalid. Token validation failed.'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  '':
                    type: string
                    x-stoplight:
                      id: mvronr4c6zd3c
              examples:
                Bad client ID:
                  value:
                    error: invalid_ client
                    error description: 'Client authentication failed (e.g., unknown client, no client authentication included, or unsupported authentication method).'
                Bad client secret:
                  value:
                    error: invalid_ client
                    error description: 'Client authentication failed (e.g., unknown client, no client authentication included, or unsupported authentication method).'
  /revoke:
    post:
      tags:
        - Tokens
      x-stoplight:
        id: c6g3jvpfxodge
      summary: Revoke
      description: |-
        This request revokes tokens granted on behalf of the end-user.

        - **Security**: Include your `client_id` and `client_secret` **in the body of the request**. Remove any information from "Basic Auth" (username and password) in Try it. 
      operationId: revoke-token
      parameters:
        - name: akoyaId
          in: header
          schema:
            type: string
          deprecated: true
          description: 'Deprecated. Do not use. Trace ID for troubleshooting. Required until deprecated October 1, 2021. Akoya will automatically generate an ID and return it in the response header `x-akoya-interaction-id`'
      requestBody:
        content:
          application/x-www-form-urlencoded:
            encoding: {}
            schema:
              required:
                - token
                - client_id
                - client_secret
                - token_type_hint
              type: object
              properties:
                client_id:
                  type: string
                  description: Client ID
                  example: <<client_id>>
                client_secret:
                  type: string
                  description: Client secret
                  example: <<client_secret>>
                token:
                  type: string
                  description: Refresh token
                  example: <<refresh_token>>
                token_type_hint:
                  type: string
                  description: Accepts `refresh_token`
                  default: refresh_token
                  example: refresh_token
      deprecated: false
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties: {}
              examples:
                OK:
                  value: {}
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  error description:
                    type: string
                x-examples:
                  Example 1:
                    error: invalid_ client
                    error description: Invalid client credentials.
              examples:
                Missing clientId or secret:
                  value:
                    error: invalid_ client
                    error description: Invalid client credentials.
                Bad token hint:
                  value:
                    error: unsupported_token_type
                Missing token:
                  value:
                    error: invalid _request
                Bad token:
                  value:
                    error: invalid _request
                Missing token hint:
                  value:
                    error: unsupported_token_type
                Revoking an already revoked token:
                  value:
                    error: invalid_request
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                x-examples:
                  Example 1:
                    error: unauthorized client
              examples:
                Bad client ID:
                  value:
                    error: unauthorized client
                Bad client secret:
                  value:
                    error: unauthorized client
      security:
        - {}
    parameters: []
components:
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
      description: 'For Basic Auth, use your `client_id` and `client_secret` for username & password'
  schemas:
    obtainTokenRequest:
      title: Obtain tokens
      x-stoplight:
        id: omgz5algk6bfm
      type: object
      required:
        - grant_type
        - redirect_uri
        - code
      properties:
        grant_type:
          type: string
          description: Set to `authorization_code` to indicate an authorization code will be returned
          default: authorization_code
        redirect_uri:
          type: string
          description: URI where user will be redirected after end-users authorization is complete. It must be the same as the URI called in the authorization request
        code:
          type: string
          description: Authorization code from end-user's authentication.
      description: |-
        The issued JWT will have an expiration that is set by the provider and will be valid only for the data permissioned by the end-user.

        Required: 
        - `grant_type`. Use `authorization_code` as the grant type.
        - `redirect_uri`. You must include your app's registered redirect uri.
        - `code`. To obtain id and refresh tokens, you must first obtain an authorization code. Pass it in the body of the request as code. Note, the code expires in 5 minutes.
    refreshTokenRequest:
      title: Refresh tokens
      x-stoplight:
        id: 12y9ah8ziezdk
      description: 'Once the ID Token expires, you will need to call the token endpoint to obtain a new set of tokens. The refresh token expiration is set by the data provider.'
      type: object
      required:
        - grant_type
        - refresh_token
        - client_id
        - client_secret
      properties:
        grant_type:
          type: string
          description: Set to `refresh_token` to indicate a new id token will be returned
          default: refresh_token
        refresh_token:
          type: string
          description: The refresh token
        client_id:
          type: string
          description: Your app's client ID from Akoya
        client_secret:
          type: string
          description: Your app's Client secret
      x-examples:
        example-1:
          value:
            grant_type: refresh_token
            refresh_token: string
            client_id: string
            client_secret: string
    tokenResponse:
      title: Token Example Response
      x-stoplight:
        id: 1ylo9l505aoby
      required:
        - token_type
        - expires_in
        - refresh_token
        - id_token
      type: object
      properties:
        token_type:
          type: string
        expires_in:
          type: integer
          format: int32
        refresh_token:
          type: string
        id_token:
          type: string
      example:
        token_type: bearer
        expires_in: 86399
        refresh_token: ChlnNm5hdWV4ZWN0aWdpdmJvdn...ZXZwbXNpaXh5ZWN6dWE3a21kbjZt
        id_token: eyJhbGciOiJSUzI1NiIsImtpZCI6IjJ...lAQGaJAsWlA3YdBBaL2ftE-v2g4fctKOug
x-headers: []
x-explorer-enabled: true
x-proxy-enabled: true
x-samples-enabled: true
x-samples-languages:
  - curl
  - node
  - ruby
  - javascript
  - python
  - csharp
x-internal: true