Token OpenAPI

openapi: 3.1.0
info:
  title: Token API v2.2
  description: Akoya Token APIs for data recipients. Default servers are set to override for the Akoya sandbox environment.
  version: '2.00'
  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
      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'
                - $ref: '#/components/schemas/refreshTokenRequest'
        description: ''
      deprecated: false
      responses:
        '200':
          description: OK
          content:
            application/x-www-form-urlencoded: {}
            application/json:
              schema:
                $ref: '#/components/schemas/tokenResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
              example:
                error: invalid_request
                error_description: Invalid or expired code parameter.
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
              example:
                error: invalid_client
                error_description: Invalid client credentials.
  /revoke:
    post:
      tags:
        - Tokens
      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: {}
      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
      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
      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
      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
    error:
      title: Error response
      type: object
      properties:
        error:
          type: string
        error_description:
          type: string
x-headers: []
x-explorer-enabled: true
x-proxy-enabled: true
x-samples-enabled: true
x-samples-languages:
  - curl
  - node
  - ruby
  - javascript
  - python
  - csharp