---
title: "Create a service token"
method: POST
path: "/organizations/{organization}/service-tokens"
tags: ["Service tokens"]
---

# Create a service token

`POST /organizations/{organization}/service-tokens`

Create a new service token for the organization.
### Authorization
A service token   must have at least one of the following access   in order to use this API endpoint:

**Service Token Accesses**
 `write_service_tokens`

## Path parameters

- `organization` string, required

## Request body

- object
  - `name` string — The name of the service token
  - `ttl` integer — Time to live (in seconds) for the service token. The token will be invalid when TTL has passed

## Response `200`

Returns the created service token with the plaintext token

- object
  - `id` string, required — The ID of the service token
  - `name` string, nullable, required — The name of the service token
  - `display_name` string, required — The display name of the service token
  - `token` string, nullable — The plaintext token. Available only after create.
  - `plain_text_refresh_token` string, nullable — The plaintext refresh token. Available only after create.
  - `avatar_url` string, required — The image source for the avatar of the service token
  - `created_at` string, required — When the service token was created
  - `updated_at` string, required — When the service token was last updated
  - `expires_at` string, nullable, required — When the service token will expire
  - `last_used_at` string, nullable, required — When the service token was last used
  - `actor_id` string, nullable, required — The ID of the actor on whose behalf the service token was created
  - `actor_display_name` string, nullable, required — The name of the actor on whose behalf the service token was created
  - `actor_type` string, nullable, required — The type of the actor on whose behalf the service token was created
  - `service_token_accesses` object[], nullable
    - `id` string, required — The ID of the service token access
    - `access` string, required — The name of the service token access
    - `description` string, required — The description of the service token access
    - `resource_name` string, required — The name of the resource the service token access gives access to
    - `resource_id` string, required — The ID of the resource the service token access gives access to
    - `resource_type` string, required — The type of the resource the service token access gives access to
    - `resource` object, required
      - `id` string, required — The ID for the resource
      - `name` string, required — The name for the resource
      - `created_at` string, required — When the resource was created
      - `updated_at` string, required — When the resource was last updated
      - `deleted_at` string, nullable, required — When the resource was deleted, if deleted
  - `oauth_accesses_by_resource` object, nullable
    - `database` object, required
      - `databases` object[], required
        - `name` string, required — the name of the database the token has access to
        - `id` string, required — the id of the database the token has access to
        - `organization` string, required — the name of the database's organization
        - `url` string, required — the planetscale app url for the database
      - `accesses` object[], required
        - `name` string, required — The name of the access scope
        - `description` string, required — The scope description
    - `organization` object, required
      - `organizations` object[], required
        - `name` string, required — the name of the organization
        - `id` string, required — the id of the organization
        - `url` string, required — the planetscale app url for the organization
      - `accesses` object[], required
        - `name` string, required — The name of the access scope
        - `description` string, required — The scope description
    - `branch` object, required
      - `branches` object[], required
        - `name` string, required — the name of the branch
        - `id` string, required — the id of the branch
        - `database` string, required — the name of the database the branch belongs to
        - `organization` string, required — the name of the organization the branch belongs to
        - `url` string, required — the planetscale app url for the branch
      - `accesses` object[], required
        - `name` string, required — The name of the access scope
        - `description` string, required — The scope description
    - `user` object, required
      - `users` object[], required
        - `name` string, required — the name of the user
        - `id` string, required — the id of the user
      - `accesses` object[], required
        - `name` string, required — The name of the access scope
        - `description` string, required — The scope description

## Other responses

- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `500` — Internal Server Error

## Changes

- **2026-06-01** `72506953f367` — 15 breaking
  - the response property `actor_display_name` became nullable for the status `200`
  - the response property `actor_id` became nullable for the status `200`
  - the response property `actor_type` became nullable for the status `200`
  - the response property `expires_at` became nullable for the status `200`
  - …11 more
- **2026-01-15** `dc925104456c` — 1 info
  - added the new optional request property `ttl`
- **2025-12-04** `5e881928d77a` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/planetscale/apis/planetscale-api/changes/organizations/:organization/service-tokens/post.md)

---

[API](https://skmtc.dev/planetscale/apis/planetscale-api.md) · [All operations](https://skmtc.dev/planetscale/apis/planetscale-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/planetscale/planetscale-api/revisions/d3bf8cec0492/schema)