GIgitguardian
API Tokens

Create an API token.

Changed on

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.

post/v1/api_tokens

Request

  • Base URL
    https://api.gitguardian.com
  • URL
    https://api.gitguardian.com/v1/api_tokens
  • Auth
    HTTP bearer

Request body

namestring 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.

scopesstring[] 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.

lifetimeinteger required

Number of days before the token expires, starting from its creation.

Example request

{
  "name": "myTokenName",
  "type": "personal_access_token",
  "scopes": [
    "incidents:read",
    "scan"
  ],
  "lifetime": 30
}

Response

API token created

idstring

Id of API token

namestring

Name of API token

workspace_idinteger

Workspace id

type'personal_access_token' | 'service_account'
status'active' | 'expired' | 'revoked'
created_atstring date-time

Creation date of the API token

last_used_atstring date-time nullable

Last usage of the API token

expire_atstring date-time nullable

Expiration date of the API token

revoked_atstring date-time nullable

Revocation date of the API token

member_idinteger nullable

Member id

creator_idinteger nullable

Creator id

scopesstring[]

List of scopes

keystring

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.

Example response

{
  "id": "5ddaad0c-5a0c-4674-beb5-1cd198d13360",
  "name": "myTokenName",
  "workspace_id": 42,
  "type": "personal_access_token",
  "status": "revoked",
  "created_at": "2023-05-20T12:40:55.662949Z",
  "last_used_at": "2023-05-24T12:40:55.662949Z",
  "revoked_at": "2023-05-27T12:40:55.662949Z",
  "member_id": 22015,
  "creator_id": 22015,
  "scopes": [
    "incidents:read",
    "scan"
  ],
  "key": "gg_pat_AbCdEf123456..."
}

Changes

  • 426ea32f227aRevision changes
    • warning

      added the new nhi:read enum value to the // response property for the response status

    • warning

      added the new nhi:write enum value to the // response property for the response status

    • info

      added the new nhi:read enum value to the request property /

    • info

      added the new nhi:write enum value to the request property /

  • 60f786a4fd4cRevision changes
    • warning

      added the new custom_tags:read enum value to the // response property for the response status

    • warning

      added the new custom_tags:write enum value to the // response property for the response status

    • warning

      added the new health_checks:read enum value to the // response property for the response status

    • warning

      added the new health_checks:write enum value to the // response property for the response status

    • warning

      added the new public-perimeter:read enum value to the // response property for the response status

    • warning

      added the new scan:create-incidents enum value to the // response property for the response status

    • warning

      added the new secrets:read enum value to the // response property for the response status

    • warning

      added the new secrets:write enum value to the // response property for the response status

    • warning

      added the new sources:scan enum value to the // response property for the response status

    • info

      added the new custom_tags:read enum value to the request property /

    • info

      added the new custom_tags:write enum value to the request property /

    • info

      added the new health_checks:read enum value to the request property /

    • info

      added the new health_checks:write enum value to the request property /

    • info

      added the new public-perimeter:read enum value to the request property /

    • info

      added the new scan:create-incidents enum value to the request property /

    • info

      added the new secrets:read enum value to the request property /

    • info

      added the new secrets:write enum value to the request property /

    • info

      added the new sources:scan enum value to the request property /