---
updatedAt: 2025-09-24T23:46:02.000Z
agentTools:
  projectIndex: https://developer.candis.io/llms.txt
---

# Create or refresh access token

This endpoint handles both authorization code exchange for tokens and refresh token exchange for new tokens based on the grant_type provided.

Reference:

1. [How to Authenticate](https://developer.candis.io/docs/how-to-authenticate)
2. [Token exchange](https://developer.candis.io/docs/token-exchange)
3. [Token Scopes](https://developer.candis.io/docs/access-token-scopes)

# OpenAPI definition

```json
{
  "openapi": "3.0.0",
  "info": {
    "title": "Authorization",
    "version": "1.0.0",
    "description": "",
    "contact": {
      "url": "https://developer.candis.io"
    },
    "x-logo": {
      "url": "https://www.candis.io/img/candis-logo-black.svg",
      "altText": "Candis GmbH"
    }
  },
  "components": {
    "schemas": {
      "TokenResponse": {
        "type": "object",
        "properties": {
          "access_token": {
            "type": "string",
            "description": "The access token issued by the authorization server."
          },
          "refresh_token": {
            "type": "string",
            "description": "A token that can be used to obtain a new access token when the original expires."
          },
          "token_type": {
            "type": "string",
            "description": "The type of token issued (usually 'Bearer')."
          },
          "expires_in": {
            "type": "integer",
            "description": "The lifetime in seconds of the access token."
          },
          "refresh_expires_in": {
            "type": "integer",
            "description": "The lifetime in seconds of the refresh token."
          },
          "scope": {
            "type": "string",
            "description": "The scopes associated with the access token."
          }
        }
      },
      "AuthorizationCodeRequest": {
        "type": "object",
        "required": [
          "grant_type",
          "code",
          "redirect_uri"
        ],
        "properties": {
          "grant_type": {
            "type": "string",
            "enum": [
              "authorization_code"
            ],
            "description": "Must be 'authorization_code' for authorization code flow."
          },
          "code": {
            "type": "string",
            "description": "The authorization code received from the authorization request."
          },
          "redirect_uri": {
            "type": "string",
            "description": "The same redirect_uri that was used in the authorization request."
          }
        }
      },
      "RefreshTokenRequest": {
        "type": "object",
        "required": [
          "grant_type",
          "refresh_token"
        ],
        "properties": {
          "grant_type": {
            "type": "string",
            "enum": [
              "refresh_token"
            ],
            "description": "Must be 'refresh_token' for refresh token flow."
          },
          "refresh_token": {
            "type": "string",
            "description": "The refresh token received during the initial token exchange."
          }
        }
      }
    },
    "securitySchemes": {
      "BasicAuth": {
        "type": "http",
        "scheme": "basic",
        "description": "Client ID and Client Secret as a header for BasicAuth."
      }
    }
  },
  "servers": [
    {
      "description": "Candis API Authorization Server.",
      "url": "https://id.my.candis.io/auth/realms/candis/protocol/openid-connect"
    }
  ],
  "tags": [
    {
      "name": "OAuth 2.0 Authorization Code Flow",
      "description": "Endpoints for authorization and token exchange.",
      "externalDocs": {
        "description": "Related (external) documentation OAuth 2.0 Authorization Code Flow.",
        "url": "https://oauth.net/2/grant-types/authorization-code/"
      }
    }
  ],
  "paths": {
    "/token": {
      "post": {
        "tags": [
          "OAuth 2.0 Authorization Code Flow"
        ],
        "security": [
          {
            "BasicAuth": []
          }
        ],
        "summary": "Create or refresh access token",
        "description": "This endpoint handles both authorization code exchange for tokens and refresh token exchange for new tokens based on the grant_type provided.",
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/AuthorizationCodeRequest",
                    "title": "Authorization Code Request"
                  },
                  {
                    "$ref": "#/components/schemas/RefreshTokenRequest",
                    "title": "Refresh Token Request"
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Access token and refresh token are returned.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TokenResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request, such as missing parameters or invalid grant type."
          }
        }
      }
    }
  },
  "x-readme": {
    "explorer-enabled": true,
    "proxy-enabled": true
  }
}
```