Jump to

• Request
• Response

Get a token using an OAuth2 flow

post

{scheme}://{host}/{basePath}/v1/auth/token

Exchange credentials for a token using the OAuth2 client credentials flow or token exchange. This endpoint is used for three purposes - 1. To exchange client credentials (client ID and secret) for an access token This uses the client credentials flow. 2. To exchange a client token and an identity token for a more specific access token This uses the token exchange flow. 3. To exchange an access token for one with the same claims and a refreshed expiration period This uses the token exchange flow. For example, a catalog client may be configured with client credentials from the OAuth2 Authorization flow. This client would exchange its client ID and secret for an access token using the client credentials request with this endpoint (1). Subsequent requests would then use that access token. Some clients may also handle sessions that have additional user context. These clients would use the token exchange flow to exchange a user token (the "subject" token) from the session for a more specific access token for that user, using the catalog's access token as the "actor" token (2). The user ID token is the "subject" token and can be any token type allowed by the OAuth2 token exchange flow, including a unsecured JWT token with a sub claim. This request should use the catalog's bearer token in the "Authorization" header. Clients may also use the token exchange flow to refresh a token that is about to expire by sending a token exchange request (3). The request's "subject" token should be the expiring token. This request should use the subject token in the "Authorization" header.

Request

There are no request parameters for this operation.

Supported Media Types

• application/x-www-form-urlencoded

Request Body - application/x-www-form-urlencoded ()

Root Schema : schema

Type: object

OAuth2 token request. Use `grant_type` to indicate the flow: `client_credentials` or `urn:ietf:params:oauth:grant-type:token-exchange`.

Show Source

• actor_token: string
  Actor token for token exchange request
• actor_token_type: string
  Allowed Values: [ "urn:ietf:params:oauth:token-type:access_token", "urn:ietf:params:oauth:token-type:refresh_token", "urn:ietf:params:oauth:token-type:id_token", "urn:ietf:params:oauth:token-type:saml1", "urn:ietf:params:oauth:token-type:saml2", "urn:ietf:params:oauth:token-type:jwt" ]

  Token type identifier, from RFC 8693 Section 3 See https://datatracker.ietf.org/doc/html/rfc8693#section-3
• client_id: string
  Client ID This can be sent in the request body, but OAuth2 recommends sending it in a Basic Authorization header.
• client_secret: string
  Client secret This can be sent in the request body, but OAuth2 recommends sending it in a Basic Authorization header.
• grant_type(required): string
  Allowed Values: [ "client_credentials", "urn:ietf:params:oauth:grant-type:token-exchange" ]
• requested_token_type: string
  Allowed Values: [ "urn:ietf:params:oauth:token-type:access_token", "urn:ietf:params:oauth:token-type:refresh_token", "urn:ietf:params:oauth:token-type:id_token", "urn:ietf:params:oauth:token-type:saml1", "urn:ietf:params:oauth:token-type:saml2", "urn:ietf:params:oauth:token-type:jwt" ]

  Token type identifier, from RFC 8693 Section 3 See https://datatracker.ietf.org/doc/html/rfc8693#section-3
• scope: string
• subject_token: string
  Subject token for token exchange request
• subject_token_type: string
  Allowed Values: [ "urn:ietf:params:oauth:token-type:access_token", "urn:ietf:params:oauth:token-type:refresh_token", "urn:ietf:params:oauth:token-type:id_token", "urn:ietf:params:oauth:token-type:saml1", "urn:ietf:params:oauth:token-type:saml2", "urn:ietf:params:oauth:token-type:jwt" ]

  Token type identifier, from RFC 8693 Section 3 See https://datatracker.ietf.org/doc/html/rfc8693#section-3

{
    "description":"OAuth2 token request. Use `grant_type` to indicate the flow: `client_credentials` or `urn:ietf:params:oauth:grant-type:token-exchange`.",
    "type":"object",
    "required":[
        "grant_type"
    ],
    "properties":{
        "grant_type":{
            "type":"string",
            "enum":[
                "client_credentials",
                "urn:ietf:params:oauth:grant-type:token-exchange"
            ]
        },
        "scope":{
            "type":"string"
        },
        "client_id":{
            "type":"string",
            "description":"Client ID\n\nThis can be sent in the request body, but OAuth2 recommends sending it in a Basic Authorization header."
        },
        "client_secret":{
            "type":"string",
            "description":"Client secret\n\nThis can be sent in the request body, but OAuth2 recommends sending it in a Basic Authorization header."
        },
        "requested_token_type":{
            "$ref":"#/components/schemas/TokenType"
        },
        "subject_token":{
            "type":"string",
            "description":"Subject token for token exchange request"
        },
        "subject_token_type":{
            "$ref":"#/components/schemas/TokenType"
        },
        "actor_token":{
            "type":"string",
            "description":"Actor token for token exchange request"
        },
        "actor_token_type":{
            "$ref":"#/components/schemas/TokenType"
        }
    }
}

Back to Top

Response

200 Response

OAuth2 token response for client credentials or token exchange

Body ()

Root Schema : OAuthTokenResponse

Type: object

Show Source

• access_token(required): string
  The access token, for client credentials or token exchange
• expires_in: integer
  Lifetime of the access token in seconds for client credentials or token exchange
• issued_token_type: string
  Allowed Values: [ "urn:ietf:params:oauth:token-type:access_token", "urn:ietf:params:oauth:token-type:refresh_token", "urn:ietf:params:oauth:token-type:id_token", "urn:ietf:params:oauth:token-type:saml1", "urn:ietf:params:oauth:token-type:saml2", "urn:ietf:params:oauth:token-type:jwt" ]

  Token type identifier, from RFC 8693 Section 3 See https://datatracker.ietf.org/doc/html/rfc8693#section-3
• refresh_token: string
  Refresh token for client credentials or token exchange
• scope: string
  Authorization scope for client credentials or token exchange
• token_type(required): string
  Allowed Values: [ "bearer", "mac", "N_A" ]

  Access token type for client credentials or token exchange See https://datatracker.ietf.org/doc/html/rfc6749#section-7.1

{
    "type":"object",
    "required":[
        "access_token",
        "token_type"
    ],
    "properties":{
        "access_token":{
            "type":"string",
            "description":"The access token, for client credentials or token exchange"
        },
        "token_type":{
            "type":"string",
            "enum":[
                "bearer",
                "mac",
                "N_A"
            ],
            "description":"Access token type for client credentials or token exchange\n\nSee https://datatracker.ietf.org/doc/html/rfc6749#section-7.1"
        },
        "expires_in":{
            "type":"integer",
            "description":"Lifetime of the access token in seconds for client credentials or token exchange"
        },
        "issued_token_type":{
            "$ref":"#/components/schemas/TokenType"
        },
        "refresh_token":{
            "type":"string",
            "description":"Refresh token for client credentials or token exchange"
        },
        "scope":{
            "type":"string",
            "description":"Authorization scope for client credentials or token exchange"
        }
    }
}

400 Response

OAuth2 error response

Body ()

Root Schema : OAuthError

Type: object

Show Source

• error(required): string
  Allowed Values: [ "invalid_request", "invalid_client", "invalid_grant", "unauthorized_client", "unsupported_grant_type", "invalid_scope" ]
• error_description: string
• error_uri: string

{
    "type":"object",
    "required":[
        "error"
    ],
    "properties":{
        "error":{
            "type":"string",
            "enum":[
                "invalid_request",
                "invalid_client",
                "invalid_grant",
                "unauthorized_client",
                "unsupported_grant_type",
                "invalid_scope"
            ]
        },
        "error_description":{
            "type":"string"
        },
        "error_uri":{
            "type":"string"
        }
    }
}

401 Response

OAuth2 error response

Body ()

Root Schema : OAuthError

Type: object

Show Source

• error(required): string
  Allowed Values: [ "invalid_request", "invalid_client", "invalid_grant", "unauthorized_client", "unsupported_grant_type", "invalid_scope" ]
• error_description: string
• error_uri: string

{
    "type":"object",
    "required":[
        "error"
    ],
    "properties":{
        "error":{
            "type":"string",
            "enum":[
                "invalid_request",
                "invalid_client",
                "invalid_grant",
                "unauthorized_client",
                "unsupported_grant_type",
                "invalid_scope"
            ]
        },
        "error_description":{
            "type":"string"
        },
        "error_uri":{
            "type":"string"
        }
    }
}

5XX Response

OAuth2 error response

Body ()

Root Schema : OAuthError

Type: object

Show Source

• error(required): string
  Allowed Values: [ "invalid_request", "invalid_client", "invalid_grant", "unauthorized_client", "unsupported_grant_type", "invalid_scope" ]
• error_description: string
• error_uri: string

{
    "type":"object",
    "required":[
        "error"
    ],
    "properties":{
        "error":{
            "type":"string",
            "enum":[
                "invalid_request",
                "invalid_client",
                "invalid_grant",
                "unauthorized_client",
                "unsupported_grant_type",
                "invalid_scope"
            ]
        },
        "error_description":{
            "type":"string"
        },
        "error_uri":{
            "type":"string"
        }
    }
}

Back to Top