# Obtain Access Token

Endpoint to obtain an OAuth 2.0 access token using the Client Credentials Grant. Clients authenticate with their ID and secret, receiving an access token for resource access.

The request must be formatted using the `application/x-www-form-urlencoded` media type.


# OpenAPI definition

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "Authentication",
    "version": "2.0.0",
    "description": "Collection of endpoints to support authentication."
  },
  "servers": [
    {
      "url": "https://api.personio.de"
    }
  ],
  "paths": {
    "/v2/auth/token": {
      "description": "The OAuth2.0 token endpoint.",
      "summary": "Obtain Access Token",
      "post": {
        "tags": [
          "Authentication"
        ],
        "description": "Endpoint to obtain an OAuth 2.0 access token using the Client Credentials Grant. Clients authenticate with their ID and secret, receiving an access token for resource access.\n\nThe request must be formatted using the `application/x-www-form-urlencoded` media type.\n",
        "requestBody": {
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "$ref": "#/components/schemas/OAuth2TokenRequest"
              },
              "examples": {
                "Success - Access Token": {
                  "$ref": "#/components/examples/OAuth2TokenSuccessAccessTokenRequest"
                },
                "Bad Request - Required Parameters Missing": {
                  "$ref": "#/components/examples/OAuth2TokenRequiredParametersMissingRequest"
                },
                "Bad Request - Invalid Client": {
                  "$ref": "#/components/examples/OAuth2TokenInvalidClientRequest"
                },
                "Bad Request - Invalid Grant": {
                  "$ref": "#/components/examples/OAuth2TokenInvalidGrantTypeRequest"
                },
                "Bad Request - Invalid Credentials": {
                  "$ref": "#/components/examples/OAuth2TokenUnauthorizedClientRequest"
                },
                "Bad Request - Unsupported Grant Type": {
                  "$ref": "#/components/examples/OAuth2TokenUnsupportedGrantTypeRequest"
                },
                "Bad Request - Invalid Scope": {
                  "$ref": "#/components/examples/OAuth2TokenInvalidScopeRequest"
                }
              }
            }
          }
        },
        "x-path-examples": {
          "Success - Access Token": {
            "value": "/v2/auth/token"
          },
          "Bad Request - Required Parameters Missing": {
            "value": "/v2/auth/token"
          },
          "Bad Request - Invalid Request Content Type": {
            "value": "/v2/auth/token"
          },
          "Bad Request - Invalid Client": {
            "value": "/v2/auth/token"
          },
          "Bad Request - Invalid Grant": {
            "value": "/v2/auth/token"
          },
          "Bad Request - Invalid Credentials": {
            "value": "/v2/auth/token"
          },
          "Bad Request - Unsupported Grant Type": {
            "value": "/v2/auth/token"
          },
          "Bad Request - Invalid Scope": {
            "value": "/v2/auth/token"
          }
        },
        "responses": {
          "200": {
            "description": "The request was successful and a response is returned based on the OAuth2.0 grant type flow.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OAuth2Token"
                },
                "examples": {
                  "Success - Access Token": {
                    "$ref": "#/components/examples/OAuth2TokenSuccessAccessToken"
                  }
                }
              }
            }
          },
          "400": {
            "description": "The current request is invalid. Please make sure you pass all the required parameters and you are using the proper content-type.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/OAuth2TokenErrorResponse"
                },
                "examples": {
                  "Bad Request - Required Parameters Missing": {
                    "$ref": "#/components/examples/OAuth2TokenRequiredParametersMissing"
                  },
                  "Bad Request - Invalid Request Content Type": {
                    "$ref": "#/components/examples/OAuth2TokenInvalidRequestContentType"
                  },
                  "Bad Request - Invalid Client": {
                    "$ref": "#/components/examples/OAuth2TokenInvalidClient"
                  },
                  "Bad Request - Invalid Grant": {
                    "$ref": "#/components/examples/OAuth2TokenInvalidGrant"
                  },
                  "Bad Request - Invalid Credentials": {
                    "$ref": "#/components/examples/OAuth2TokenUnauthorizedClient"
                  },
                  "Bad Request - Unsupported Grant Type": {
                    "$ref": "#/components/examples/OAuth2TokenUnsupportedGrantType"
                  },
                  "Bad Request - Invalid Scope": {
                    "$ref": "#/components/examples/OAuth2TokenInvalidScope"
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "OAuth2TokenRequest": {
        "description": "The request for the OAuth2.0 client credentials grant type.",
        "type": "object",
        "properties": {
          "client_id": {
            "description": "The client's unique identifier.",
            "example": "papi-dcec6d81-8c0f-47f0-9dd8-4e59755f041a",
            "type": "string"
          },
          "client_secret": {
            "description": "The client's secret key.",
            "example": "papi-FTcGcxmX_dmH2AkBARp2ms8VDZvQtJQJ0j0sdIJRrRrXdlTytZOr5QLY1fLYGEeWRzmb7e5Cqd7GIdjnMj0Z7w",
            "type": "string"
          },
          "grant_type": {
            "description": "The grant type being used. At the moment, only `client_credentials` grant type is supported.",
            "example": "client_credentials",
            "type": "string",
            "enum": [
              "client_credentials"
            ]
          },
          "scope": {
            "description": "Requested scopes for the issued token. Space-delimited list; order doesn't matter. If no scope is provided, all scopes available to the client will be assigned.\n\nExample: \"documents:read documents:write\"\n",
            "example": "documents:read documents:write",
            "type": "string"
          }
        },
        "required": [
          "grant_type",
          "client_id",
          "client_secret"
        ]
      },
      "OAuth2Token": {
        "description": "The OAuth2.0 grant type flow response.",
        "type": "object",
        "properties": {
          "access_token": {
            "description": "The access token from the grant type flow.",
            "example": "papi-OUYVj9QdAyL8F-Naa0PB7X2CZVb0uHDTYvW_FoX1o3lJBgvbcJ_ctlJ8nH4FDi6QWl5BHlzj-CheybZaxVRq0g",
            "type": "string"
          },
          "refresh_token": {
            "description": "Token to be used for refreshing the access token. Can be omitted for some grant types.",
            "example": "papi-OUYVj9QdAyL8F-Naa0PB7X2CZVb0uHDTYvW_FoX1o3lJBgvbcJ_ctlJ8nH4FDi6QWl5BHlzj-CheybZaxVRq0g",
            "nullable": true,
            "type": "string"
          },
          "token_type": {
            "description": "The type of the access token.",
            "example": "Bearer",
            "type": "string",
            "enum": [
              "Bearer"
            ]
          },
          "expires_in": {
            "description": "The remaining lifetime of the access token, expressed in seconds. The default value is 1 day.",
            "example": 86400,
            "type": "integer"
          },
          "scope": {
            "description": "Space delimited array of scopes assigned to the granted token. Order doesn't matter.",
            "example": "documents:read documents:write",
            "type": "string"
          }
        }
      },
      "OAuth2TokenErrorResponse": {
        "description": "Response in case of an error.",
        "type": "object",
        "properties": {
          "error": {
            "description": "Error type that happened, see OAuth2.0 specs.",
            "type": "string",
            "enum": [
              "invalid_request",
              "invalid_client",
              "invalid_grant",
              "unauthorized_client",
              "unsupported_grant_type",
              "invalid_scope",
              "server_error",
              "temporarily_unavailable",
              "access_denied",
              "unsupported_response_type"
            ],
            "example": "unauthorized_client"
          },
          "error_description": {
            "description": "The description of the error.",
            "type": "string",
            "nullable": true,
            "example": "The credentials were not correct. Make sure you are providing the right client_id and client_secret."
          },
          "error_uri": {
            "description": "A URI identifying a human-readable web page with additional information about the error.",
            "type": "string",
            "nullable": true,
            "example": "https://developer.personio.de/reference/errors#credentials.invalid_grant"
          },
          "timestamp": {
            "description": "The timestamp when the response was generated on the server.",
            "type": "string",
            "format": "date-time",
            "example": "2023-03-01T14:07:17Z"
          },
          "trace_id": {
            "description": "A unique trace ID used for tracking the request inside Personio system.",
            "type": "string",
            "example": "baaaaaad-c0de-fade-baad-c000000000de"
          },
          "meta": {
            "description": "Object containing meta information about the error. Can be empty.",
            "type": "object",
            "example": {
              "grant_type": "let_me_in"
            }
          }
        }
      }
    },
    "examples": {
      "OAuth2TokenSuccessAccessTokenRequest": {
        "value": {
          "grant_type": "client_credentials",
          "client_id": "papi-baaaaaad-c0de-fade-baad-00000000001d",
          "client_secret": "verY-Secret-p4ssw0rd"
        }
      },
      "OAuth2TokenRequiredParametersMissingRequest": {
        "value": {
          "client_id": "papi-baaaaaad-c0de-fade-baad-00000000001d"
        }
      },
      "OAuth2TokenInvalidClientRequest": {
        "value": {
          "grant_type": "client_credentials",
          "client_id": "client_who"
        }
      },
      "OAuth2TokenInvalidGrantTypeRequest": {
        "value": {
          "grant_type": "lilu_dallas_multipass"
        }
      },
      "OAuth2TokenUnauthorizedClientRequest": {
        "value": {
          "grant_type": "client_credentials",
          "client_id": "papi-baaaaaad-c0de-fade-baad-00000000001d",
          "client_secret": "verY-wr0ng-p4ssw0rd"
        }
      },
      "OAuth2TokenUnsupportedGrantTypeRequest": {
        "value": {
          "grant_type": "urn:ietf:params:oauth:grant-type:device_code"
        }
      },
      "OAuth2TokenInvalidScopeRequest": {
        "value": {
          "grant_type": "client_credentials",
          "client_id": "papi-baaaaaad-c0de-fade-baad-00000000001d",
          "client_secret": "verY-s3cr3t-p4ssw0rd",
          "scope": "personio:person:read fake_scope:777"
        }
      },
      "OAuth2TokenSuccessAccessToken": {
        "value": {
          "access_token": "papi-OUYVj9QdAyL8F-Naa0PB7X2CZVb0uHDTYvW_FoX1o3lJBgvbcJ_ctlJ8nH4FDi6QWl5BHlzj-CheybZaxVRq0g",
          "expires_in": 86400,
          "token_type": "Bearer",
          "scope": "personio:person:write personio:employment:read"
        }
      },
      "OAuth2TokenRequiredParametersMissing": {
        "value": {
          "timestamp": "2023-03-01T14:07:17Z",
          "trace_id": "baaaaaad-c0de-fade-baad-c000000000de",
          "error": "invalid_request",
          "error_description": "The request has missing or invalid required parameters.",
          "error_uri": "https://developer.personio.de/reference/errors#credentials.oauth2.invalid_request.required_parameters_missing",
          "meta": {
            "missing_parameters": [
              "grant_type"
            ]
          }
        }
      },
      "OAuth2TokenInvalidRequestContentType": {
        "value": {
          "timestamp": "2023-03-01T14:07:17Z",
          "trace_id": "baaaaaad-c0de-fade-baad-c000000000de",
          "error": "invalid_request",
          "error_description": "The content type of the request must be \"application/x-www-form-urlencoded\".",
          "type": "https://developer.personio.de/reference/errors#credentials.oauth2.invalid_request.invalid_request_content_type"
        }
      },
      "OAuth2TokenInvalidClient": {
        "value": {
          "timestamp": "2023-03-01T14:07:17Z",
          "trace_id": "baaaaaad-c0de-fade-baad-c000000000de",
          "error": "invalid_client",
          "error_description": "Client authentication failed (e.g., unknown client, wrong secret, no client authentication included, or unsupported authentication method).",
          "error_uri": "https://developer.personio.de/reference/errors#credentials.oauth2.invalid_client"
        }
      },
      "OAuth2TokenInvalidGrant": {
        "value": {
          "timestamp": "2023-03-01T14:07:17Z",
          "trace_id": "baaaaaad-c0de-fade-baad-c000000000de",
          "error": "invalid_grant",
          "error_description": "Error in the authorization flow. Examples: client doesn't have access to all attributes in the requested scope, refresh token has been revoked, authorization code has already been consumed...",
          "error_uri": "https://developer.personio.de/reference/errors#credentials.oauth2.invalid_grant"
        }
      },
      "OAuth2TokenUnauthorizedClient": {
        "value": {
          "timestamp": "2023-03-01T14:07:17Z",
          "trace_id": "baaaaaad-c0de-fade-baad-c000000000de",
          "error": "unauthorized_client",
          "error_description": "Client is not allowed to use the specified grant type flow.",
          "error_uri": "https://developer.personio.de/reference/errors#credentials.oauth2.unauthorized_client"
        }
      },
      "OAuth2TokenUnsupportedGrantType": {
        "value": {
          "timestamp": "2023-03-01T14:07:17Z",
          "trace_id": "baaaaaad-c0de-fade-baad-c000000000de",
          "error": "unsupported_grant_type",
          "error_description": "The requested authorization grant type is not supported by the server.",
          "error_uri": "https://developer.personio.de/reference/errors#credentials.oauth2.unsupported_grant_type",
          "meta": {
            "grant_type": "urn:ietf:params:oauth:grant-type:device_code"
          }
        }
      },
      "OAuth2TokenInvalidScope": {
        "value": {
          "timestamp": "2023-03-01T14:07:17Z",
          "trace_id": "baaaaaad-c0de-fade-baad-c000000000de",
          "error": "invalid_scope",
          "error_description": "One of the requested scopes is invalid.",
          "error_uri": "https://developer.personio.de/reference/errors#credentials.oauth2.invalid_scope"
        }
      }
    }
  }
}
```