---
title: "Create a personal access token"
method: POST
path: "/tokens"
tags: ["admin"]
---

# Create a personal access token

`POST /tokens`

## Request

- Base URL: `https://api.letsship.ai/v1`
- URL: `https://api.letsship.ai/v1/tokens`
- Auth: HTTP bearer

Creates a personal access token (pat_) for the signed-in user in their organization. Tokens are created from a signed-in session, never by another token. The requested scopes must exist and must be within the user's own permissions: a token can never carry more authority than the person who created it, and a request that asks for more is refused with each offending scope named rather than quietly narrowed. The token value is returned once and cannot be retrieved again.

## Request body

- CreateTokenRequest
  - `name` string, required: Human label shown in the token list. Not an identifier.
  - `scopes` string[]: Scopes to delegate to the token. Every entry must be a declared scope AND within the caller's own grant ceiling (a token can never carry authority its minter lacks) - otherwise 403, naming each refused entry. Defaults to none.
  - `expiresInDays` integer: Lifetime in days from now. Tokens always expire; there is no non-expiring option.
  - `projectId` string: Bind the token to ONE project. Missions, runs, environments, artifacts and scheduled tasks then refuse anything outside it - the narrowest useful grant for a third-party integration. The project records themselves stay readable across the org. The project must belong to your org, otherwise 404. Omitted: the token is org-wide.

## Response `201`

Token created. `token` is shown here and never again.

- CreatedToken
  - `id` string, required
  - `name` string, required
  - `token` string, required: The raw bearer token. Shown once, at creation, and never again.
  - `scopes` string[], required
  - `projectId` string, nullable, required: The project this token is bound to, or null when it is org-wide.
  - `expiresAt` integer, required
  - `createdAt` integer, required

## Other responses

- `403`: Caller is not a human org member, or requested a scope above their grant ceiling.
- `404`: The caller belongs to no organization.

---

[API](https://skmtc.dev/letsship/apis/ship-api.md) · [All operations](https://skmtc.dev/letsship/apis/ship-api/llms.txt) · [OpenAPI document](https://skmtc.dev/letsship/apis/ship-api/revisions/e6eac1bcadd4?raw)