---
title: "Create or replace service token"
method: PUT
path: "/v1/service_token"
tags: ["ServiceTokens"]
---

# Create or replace service token

`PUT /v1/service_token`

## Request

- Base URL: `https://api.braintrust.dev`
- URL: `https://api.braintrust.dev/v1/service_token`
- Auth: one of:
  - HTTP bearer
  - none

Create or replace service token. If there is an existing service token with the same name as the one specified in the request, will replace the existing service token with the provided fields

## Request body

- object
  - `name` string, required: Name of the service token. Does not have to be unique
  - `org_name` string, nullable: For nearly all users, this parameter should be unnecessary. But in the rare case that your API key belongs to multiple organizations, you may specify the name of the organization the Service token belongs in.
  - `service_account_id` string, required: The ID of the service account to which the token should belong. To create a service account, visit [**Settings > Service tokens**](https://www.braintrust.dev/app/~/configuration/org/service-tokens) in the Braintrust UI or call [`PATCH /v1/organization/members`](https://docs.braintrust.dev/api-reference/organizations/modify-organization-membership).
  - `expires_in_seconds` integer, nullable: Number of seconds from now after which the service token should expire. If omitted, the token never expires.

## Response `200`

Returns an object containing the raw service token. This is the only time the raw API key will be exposed

- CreateServiceTokenOutput
  - `id` string, uuid, required: Unique identifier for the service token
  - `created` string, date-time, nullable: Date of service token creation
  - `name` string, required: Name of the service token
  - `preview_name` string, required: Masked preview showing the token prefix and last four characters, e.g. bt-st-…AbCd.
  - `service_account_id` string, uuid, nullable: Unique identifier for the service token
  - `service_account_email` string, nullable: The service account email (not routable)
  - `service_account_name` string, nullable: The service account name
  - `org_id` string, uuid, nullable: Unique identifier for the organization
  - `expires_at` string, date-time, nullable: Date and time at which the service token expires. If null, the token never expires.
  - `key` string, required: The raw service token. It will only be exposed this one time

## Other responses

- `400`: The request was unacceptable, often due to missing a required parameter
- `401`: No valid API key provided
- `403`: The API key doesn’t have permissions to perform the request
- `429`: Too many requests hit the API too quickly. We recommend an exponential backoff of your requests
- `500`: Something went wrong on Braintrust's end. (These are rare.)

## Changes

- **2026-10-30** `8f5039399f77`: 2 breaking, 1 info
  - the request property `expires_in_seconds` became not nullable
  - the request property `org_name` became not nullable
  - the `expires_in_seconds` request property's exclusiveMinimum was decreased from `true` to `0.00`
- **2026-09-03** `ebac33c1422e`: 1 breaking
  - request body became required
- **2026-08-13** `e05ef145579d`: 2 info
  - added the new optional request property `expires_in_seconds`
  - added the optional property `expires_at` to the response with the `200` status
- **2026-06-03** `46b20afded4f`: 1 info
  - endpoint added
- **2026-05-21** `7c3461755f69`: 1 breaking
  - api removed without deprecation

[Operation history](https://skmtc.dev/braintrustdata/apis/braintrust-api/changes/v1/service_token/put.md)

---

[API](https://skmtc.dev/braintrustdata/apis/braintrust-api.md) - [All operations](https://skmtc.dev/braintrustdata/apis/braintrust-api/llms.txt) - [OpenAPI document](https://skmtc.dev/braintrustdata/apis/braintrust-api/revisions/19184ec94018?raw)