--- title: "Create or renew an OAuth token" method: POST path: "/organizations/{organization}/oauth-applications/{id}/token" tags: ["OAuth tokens"] --- # Create or renew an OAuth token `POST /organizations/{organization}/oauth-applications/{id}/token` Create an OAuth token from an authorization grant code, or refresh an OAuth token from a refresh token ### Authorization A service token must have at least one of the following access in order to use this API endpoint: **Service Token Accesses** `write_oauth_tokens` ## Path parameters - `organization` string, required - `id` string, required ## Request body - object - `client_id` string, required — The OAuth application's client ID - `client_secret` string, required — The OAuth application's client secret - `grant_type` 'authorization_code' | 'refresh_token', required — Whether an OAuth grant code or a refresh token is being exchanged for an OAuth token - `code` string — The OAuth grant code provided to your OAuth application's redirect URI. Required when grant_type is authorization_code - `redirect_uri` string — The OAuth application's redirect URI. Required when grant_type is authorization_code - `refresh_token` string — The refresh token from the original OAuth token grant. Required when grant_type is refresh_token ## Response `200` Returns the created OAuth 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 - `403` — Forbidden - `404` — Not Found - `422` — Unprocessable Entity - `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 [Change history](https://skmtc.dev/planetscale/apis/planetscale-api/changes/organizations/:organization/oauth-applications/:id/token/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/6d28c038c4fd/schema)