> ## Documentation Index
> Fetch the complete documentation index at: https://docs.taxrock.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get or refresh a token

> Exchange an authorization code for tokens, or refresh an expired access token. The `grant_type` field selects which.

Fill in the fields for the grant you want, then **Run** it. Each request field is labeled
with the grant it applies to.

* **Exchange an authorization code** (`grant_type: authorization_code`). Run this once,
  right after a consent. The `code` is single-use, expires in about 60 seconds, and needs
  the `code_verifier` matching the challenge you sent to
  [Authorize](/api-reference/authentication/authorize).
* **Refresh an access token** (`grant_type: refresh_token`). Repeatable. Paste a stored
  refresh token to get a fresh access token. No new refresh token is returned.

<Note>
  In the sandbox, use the `client_secret` from your handoff document. The `access_token` you
  receive is the Bearer credential for the lookup endpoints.
</Note>


## OpenAPI

````yaml api-reference/oauth-token.json POST /oauth/token
openapi: 3.1.0
info:
  title: TaxRock Delegate API token
  version: 1.0.0
  description: Get or refresh a token. Lives on the login domain.
servers:
  - url: https://login-demo.taxrock.com
    description: Sandbox
  - url: https://login.taxrock.com
    description: Production
security: []
paths:
  /oauth/token:
    post:
      tags:
        - Authentication
      summary: Get or refresh a token
      description: >-
        Exchange an authorization code for tokens, or refresh an expired access
        token. The `grant_type` field selects which.
      operationId: oauthToken
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TokenRequest'
            examples:
              authorizationCode:
                summary: Exchange an authorization code
                value:
                  grant_type: authorization_code
                  client_id: YOUR_CLIENT_ID
                  client_secret: YOUR_CLIENT_SECRET
                  code: CODE_FROM_AUTHORIZE_REDIRECT
                  redirect_uri: http://localhost:0000
                  code_verifier: PKCE_VERIFIER_FROM_AUTHORIZE_STEP
              refreshToken:
                summary: Refresh an access token
                value:
                  grant_type: refresh_token
                  client_id: YOUR_CLIENT_ID
                  client_secret: YOUR_CLIENT_SECRET
                  refresh_token: YOUR_REFRESH_TOKEN
                  audience: https://delegate.api.taxrock.com
      responses:
        '200':
          description: Token issued.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
              examples:
                authorizationCode:
                  summary: From an authorization_code exchange
                  value:
                    access_token: eyJhbGciOiJSUzI1NiIsInR5c...
                    refresh_token: v1.MZ8aRq3K...
                    scope: offline_access read:client-accounts
                    expires_in: 3600
                    token_type: Bearer
                refreshToken:
                  summary: From a refresh_token grant (no new refresh token)
                  value:
                    access_token: eyJhbGciOiJSUzI1NiIsInR5c...
                    scope: offline_access read:client-accounts
                    expires_in: 3600
                    token_type: Bearer
        '400':
          description: >-
            The grant is invalid: an expired or already-used `code`, or an
            expired/revoked `refresh_token`. For the refresh grant, send the
            user back through authorization.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthError'
              examples:
                invalidGrant:
                  summary: Expired/used code or refresh token
                  value:
                    error: invalid_grant
                    error_description: >-
                      The authorization code or refresh token is invalid,
                      expired, or revoked.
        '401':
          description: Client authentication failed (bad `client_id`/`client_secret`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthError'
              examples:
                invalidClient:
                  summary: Bad client credentials
                  value:
                    error: invalid_client
                    error_description: Client authentication failed.
      security: []
components:
  schemas:
    TokenRequest:
      type: object
      required:
        - grant_type
        - client_id
        - client_secret
      description: OAuth token request. Which fields apply depends on `grant_type`.
      properties:
        grant_type:
          type: string
          enum:
            - authorization_code
            - refresh_token
          description: >-
            **Both grants:** use `authorization_code` to exchange a code, or
            `refresh_token` to refresh.
        client_id:
          type: string
          description: '**Both grants:** your client ID for the environment.'
        client_secret:
          type: string
          description: '**Both grants:** your client secret for the environment.'
        code:
          type: string
          description: >-
            **`authorization_code` grant:** the single-use code from the
            /authorize redirect. Expires in about 60 seconds.
        redirect_uri:
          type: string
          description: >-
            **`authorization_code` grant:** must match the callback registered
            with TaxRock.
        code_verifier:
          type: string
          description: >-
            **`authorization_code` grant:** the PKCE verifier matching the
            challenge sent to /authorize.
        refresh_token:
          type: string
          description: '**`refresh_token` grant:** your stored refresh token.'
        audience:
          type: string
          description: >-
            **`refresh_token` grant:** the API audience
            (https://delegate.api.taxrock.com), so the new access token targets
            the Delegate API.
    TokenResponse:
      type: object
      required:
        - access_token
        - scope
        - expires_in
        - token_type
      properties:
        access_token:
          type: string
          description: Send as a Bearer credential to the Delegate API.
        refresh_token:
          type: string
          description: >-
            **`authorization_code` grant:** the refresh grant returns no new
            refresh token, so keep using the one you have.
        scope:
          type: string
        expires_in:
          type: integer
          description: Access token lifetime in seconds (~3600).
        token_type:
          type: string
          enum:
            - Bearer
    OAuthError:
      type: object
      required:
        - error
      properties:
        error:
          type: string
          description: OAuth error code, e.g. `invalid_grant` or `invalid_client`.
        error_description:
          type: string
          description: Human-readable explanation.

````