PIpipeshub-ai
OAuth Provider

Exchange authorization code for tokens

Changed on

OAuth 2.0 Token Endpoint (RFC 6749 Section 4.1.3).

Exchanges an authorization code, client credentials, refresh token, device code or service token for access tokens. Successful responses carry Cache-Control: no-store and Pragma: no-cache.

Grant Types:

  • authorization_code: Exchange auth code for tokens (user-based)
  • client_credentials: Get tokens for machine-to-machine auth
  • urn:ietf:params:oauth:grant-type:device_code: Poll for the tokens of a device authorization (RFC 8628); answered 400 with authorization_pending until the user approves
  • refresh_token: Get new access token using refresh token. The refresh token must have been issued to the presenting client_id; one issued to another client is rejected with 400 invalid_grant and is left untouched (not rotated, not revoked).
  • urn:ietf:params:oauth:grant-type:token-exchange: Service-account delegation (RFC 8693). A service account exchanges its own token for a five-minute token that acts as one named person from its allow-list. Enterprise edition. The Community build answers this grant with unsupported_grant_type and leaves it out of discovery, so check grant_types_supported rather than assuming it is there. This grant sends no client_id or client_secret — the subject_token is the authentication, since it already carries a verified identity and the scopes that bound it. Refusals about the person asked for all return 400 invalid_target with one wording; the cause is recorded in the delegation log, which only an administrator can read.

For client_credentials, access tokens represent the service account the app is pointed at (tokenIdentityUserId), or the OAuth app creator for an app registered before that was required and never bound. The JWT may encode userId === client_id; the Node API gateway loads the application record on every request and resolves the identity from it, treating the createdBy claim as a cross-check and refusing a token whose claim no longer matches it — see OAuth Provider tag.

Client Authentication: Can be provided via:

  • HTTP Basic auth: Authorization: Basic base64(client_id:client_secret)
  • Request body: client_id and client_secret parameters

PKCE Verification: If authorization used PKCE, the code_verifier must be provided and will be verified against the stored code challenge.

post/oauth2/token

Request

  • Base URL
    https://app.pipeshub.com/api/v1
  • URL
    https://app.pipeshub.com/api/v1/oauth2/token
  • Auth
    none required

Request body

grant_type'authorization_code' | 'client_credentials' | 'refresh_token' | 'urn:ietf:params:oauth:grant-type:device_code' | 'urn:ietf:params:oauth:grant-type:token-exchange' required

OAuth grant type:

  • authorization_code: Exchange auth code for tokens
  • client_credentials: Machine-to-machine auth
  • refresh_token: Get new access token using refresh token
  • urn:ietf:params:oauth:grant-type:device_code: Poll for the tokens of a device authorization (RFC 8628) started with POST /oauth2/device_authorization
  • urn:ietf:params:oauth:grant-type:token-exchange: Service-account delegation (RFC 8693). Exchanges a service token for a short-lived token that acts as one named person. Enterprise edition; kept in this enum because the request shape is the same wherever the grant is offered.
codestring

Authorization code (required for authorization_code grant)

redirect_uristring uri

Redirect URI (required for authorization_code grant)

device_codestring

The device_code from POST /oauth2/device_authorization (required for the device_code grant; without it the answer is 400 invalid_grant)

client_idstring

Client ID (can also be sent via Basic auth header, which then takes precedence)

client_secretstring

Client secret (can also be sent via Basic auth header)

refresh_tokenstring

Refresh token (required for refresh_token grant)

scopestring

Requested scopes (optional, defaults to original grant scopes)

code_verifierstring

PKCE code verifier (RFC 7636). Required if code_challenge was used. Must be 43-128 characters from [A-Za-z0-9-._~]

subject_tokenstring

The service token being exchanged (token-exchange grant only). This is the only authentication the grant has: no client_id or client_secret is sent, because the service token already carries a verified identity and the scopes that bound it.

subject_token_typestring

Optional. Must be urn:ietf:params:oauth:token-type:access_token when sent (token-exchange grant only).

requested_subjectstring

The person to act as, by user id or email address (token-exchange grant only). Must be on the service account's allow-list, and must not be an administrator.

Response

Tokens issued successfully

access_tokenstring

The access token for API requests

token_typestring

Token type (always "Bearer")

expires_ininteger

Access token lifetime in seconds

refresh_tokenstring

Refresh token for obtaining new access tokens. Issued only when the token acts as a user (authorization_code, refresh_token and device_code grants) and the granted scopes include offline_access; never for client_credentials.

scopestring

Granted scopes, space-separated (may differ from requested). Empty for a client_credentials token whose app holds only user-bound scopes (openid, profile, email, offline_access), which are dropped from that grant.

issued_token_typestring

The type of the issued token (RFC 8693 Section 2.2.1). Returned by the token-exchange grant, where it is always urn:ietf:params:oauth:token-type:access_token.

Example response

{
  "token_type": "Bearer",
  "expires_in": 3600,
  "issued_token_type": "urn:ietf:params:oauth:token-type:access_token"
}

Changes

  • dbb5e203b445Revision changes
    • breaking

      the request property's minLength was increased from 0 to 1 (media type: application/x-www-form-urlencoded)

    • breaking

      the request property's minLength was increased from 0 to 1 (media type: application/json)

    • breaking

      the request property's minLength was increased from 0 to 1 (media type: application/x-www-form-urlencoded)

    • breaking

      the request property's minLength was increased from 0 to 1 (media type: application/json)

    • breaking

      the request property's minLength was increased from 0 to 1 (media type: application/x-www-form-urlencoded)

    • breaking

      the request property's minLength was increased from 0 to 1 (media type: application/json)

    • breaking

      added to the response body oneOf list for the response status

    • breaking

      the response's body type changed from object to no type for status

    • breaking

      removed the required property from the response with the status

    • warning

      the request property's maxLength was set to 128 (media type: application/x-www-form-urlencoded)

    • warning

      the request property's maxLength was set to 128 (media type: application/json)

    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status

    • warning

      added the new authorization_pending enum value to the response property for the response status

    • warning

      added the new expired_token enum value to the response property for the response status

    • warning

      added the new slow_down enum value to the response property for the response status

    • info

      added the new optional request property (media type: application/x-www-form-urlencoded)

    • info

      added the new optional request property (media type: application/json)

    • info

      added the new urn:ietf:params:oauth:grant-type:device_code enum value to the request property (media type: application/x-www-form-urlencoded)

    • info

      added the new urn:ietf:params:oauth:grant-type:device_code enum value to the request property (media type: application/json)

    • info

      added the non-success response with the status

  • a90ab79f26a1Revision changes
    • breaking

      the response's property type changed from object to string for status

    • breaking

      removed the required property / from the response with the status

    • breaking

      removed the required property / from the response with the status

    • warning

      removed the optional property / from the response with the status

    • warning

      removed the optional property / from the response with the status

    • warning

      added the new access_denied enum value to the response property for the response status

    • warning

      added the new invalid_client enum value to the response property for the response status

    • warning

      added the new invalid_grant enum value to the response property for the response status

    • warning

      added the new invalid_request enum value to the response property for the response status

    • warning

      added the new invalid_scope enum value to the response property for the response status

    • warning

      added the new invalid_target enum value to the response property for the response status

    • warning

      added the new invalid_target enum value to the response property for the response status

    • warning

      added the new server_error enum value to the response property for the response status

    • warning

      added the new unauthorized_client enum value to the response property for the response status

    • warning

      added the new unsupported_grant_type enum value to the response property for the response status

    • info

      added the new optional request property (media type: application/x-www-form-urlencoded)

    • info

      added the new optional request property (media type: application/json)

    • info

      added the new optional request property (media type: application/x-www-form-urlencoded)

    • info

      added the new optional request property (media type: application/json)

    • info

      added the new optional request property (media type: application/x-www-form-urlencoded)

    • info

      added the new optional request property (media type: application/json)

    • info

      added the new urn:ietf:params:oauth:grant-type:token-exchange enum value to the request property (media type: application/x-www-form-urlencoded)

    • info

      added the new urn:ietf:params:oauth:grant-type:token-exchange enum value to the request property (media type: application/json)

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status