Akoya Token API 2.2
Paste the following code into your favorite text editor and save it as a YAML file.
Documentation
Paste the following code into your favorite text editor and save it as a YAML file.
openapi: 3.1.0
x-stoplight:
id: lr4y4tjlqfit9
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: questions@akoya.com
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: ttprswov38ilk
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).
## Need More Help?
See our [interactive demo](https://akoya.coastdemo.com/share/6a3ef9a566b9a7c0a6dc46f2) which walks you through obtaining an auth code, obtaining tokens, and retrieving data.
operationId: get-token
requestBody:
content:
application/x-www-form-urlencoded:
schema:
oneOf:
- $ref: '#/components/schemas/obtainTokenRequest'
x-stoplight:
id: g63q5nmx2pg0p
- $ref: '#/components/schemas/refreshTokenRequest'
x-stoplight:
id: eqg6o9911cgfc
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
properties:
error:
type: string
error_description:
type: string
x-examples:
Example 1:
error: invalid_request
error_description: Invalid or expired code parameter.
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:
error:
type: string
error_description:
type: string
x-examples:
Example 1:
error: invalid_request
error_description: Invalid or expired code parameter.
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: e1fydyx63waeq
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
error_description:
type: string
x-examples:
Example 1:
error: invalid_request
error_description: Invalid or expired code parameter.
examples:
Invalid client credentials:
value:
error: invalid_client
error_description: Invalid client credentials.
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: j4xfxthzhdjpv
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: ihqohmdhmc66u
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: smw4cqhowc7ep
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