---
title: "Create an API token."
method: POST
path: "/v1/api_tokens"
tags: ["API Tokens"]
---

# Create an API token.

`POST /v1/api_tokens`

Create a new personal access token or service account token in the workspace.

Unlike the other API token endpoints, this one requires no particular scope:
any valid token can call it. What a token is allowed to create is bounded by
its own type and its own scopes instead.

A token can only create another token of its own type: `type` must match the
type of the token used to authenticate the call. A personal access token
therefore creates personal access tokens owned by its own member, and a
service account token creates service account tokens belonging to the
workspace. There is no way to create a token on behalf of another member.

The requested `scopes` must be a subset of the scopes of the calling token.

A service account token whose creating user no longer exists cannot create
tokens, and the call is rejected.

The response is the only place the new token's clear text `key` is exposed:
it cannot be read again from the list or retrieve endpoints.

Creation is also rejected when the name is already used by an active token of
the same type, when the workspace has reached its maximum number of active
tokens, or when the requested `lifetime` exceeds the maximum lifetime allowed
by the workspace policy.

## Request body

- object — Payload used to create a new API token.
  - `name` string, required — Name of the token. It must be unique among the active tokens of the same type: per member for a personal access token, per workspace for a service account token.
  - `type` 'personal_access_token' | 'service_account', required — Type of the token to create. It must match the type of the token used to authenticate the call.
  - `scopes` string[], required — Scopes granted to the new token. They cannot exceed the scopes of the token used to perform the call. Some scopes contain others, so the new token can come back with more scopes than requested: asking for `incidents:write` also grants `incidents:read`.
  - `lifetime` integer, required — Number of days before the token expires, starting from its creation.

## Response `201`

API token created

- object — Details of a freshly created API Token, along with its clear text key.
  - `id` string — Id of API token
  - `name` string — Name of API token
  - `workspace_id` integer — Workspace id
  - `type` 'personal_access_token' | 'service_account'
  - `status` 'active' | 'expired' | 'revoked'
  - `created_at` string, date-time — Creation date of the API token
  - `last_used_at` string, date-time, nullable — Last usage of the API token
  - `expire_at` string, date-time, nullable — Expiration date of the API token
  - `revoked_at` string, date-time, nullable — Revocation date of the API token
  - `member_id` integer, nullable — Member id
  - `creator_id` integer, nullable — Creator id
  - `scopes` string[] — List of scopes
  - `key` string — The clear text key of the new token. Use it in the `Authorization: Token <key>` header for subsequent calls to the GitGuardian API. It is returned by this endpoint only and cannot be retrieved afterwards, so store it before discarding the response.

## Other responses

- `400` — Invalid data
- `401` — Invalid API key
- `403` — Permission denied
- `409` — Another token is already being created for this member or workspace. The call can be retried after a few seconds.

---

[API](https://skmtc.net/gitguardian/apis/gitguardian-api.md) · [All operations](https://skmtc.net/gitguardian/apis/gitguardian-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/gitguardian/gitguardian-api/revisions/511b067cdcb1/schema)