Plum / developers
REST APITokens

Create a personal access token

Creates a personal access token for scripts that act as you. The response contains the token once; it cannot be read again. `expires_in_days` is required: a number of days, or `null` for a token that never expires. A never-expiring token keeps working until you revoke it, sign out everywhere, or delete your account. Requires a signed-in Plum app; a personal access token cannot create tokens. An account can hold at most 20 active (unrevoked, unexpired) tokens; creating another returns 409 `TOKEN_LIMIT_REACHED`. See [Personal access tokens](/docs/personal-access-tokens).

POST/tokens

Authorization

bearerAuth
AuthorizationBearer <token>

Send Authorization: Bearer <token> with one of: an app session access token from /auth/verify-otp or /auth/refresh; an OAuth access token from /oauth/token issued for the API origin (its scopes are its permissions); or a personal access token starting with optima_pat_ (see /docs/personal-access-tokens). Personal access tokens cannot create or list tokens, revoke other tokens, sign out, or delete or restore the account. Content routes need the permission of their layer: audio:read/audio:write for recordings, turns:read/turns:write for turns, contacts, source signals, and events, and insights:read/insights:write for suggestions and session summaries; search and recall need turns:read and insights:read. A request without the permission, or for an account whose layer is turned off, returns 403 FORBIDDEN. See /docs/authentication#scopes.

In: header

Header Parameters

X-API-Version?"1"

Send 1 to pin the documented API contract. If omitted, the latest version is selected.

Default"1"

Value in

  • "1"

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/tokens" \  -H "X-API-Version: 1" \  -H "Content-Type: application/json" \  -d '{    "name": "string",    "expires_in_days": 1  }'
{  "success": true,  "data": {    "personal_access_token": {      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "name": "string",      "last_four": "stri",      "permissions": [        "string"      ],      "created_at": "2019-08-24T14:15:22Z",      "last_used_at": "2019-08-24T14:15:22Z",      "expires_at": "2019-08-24T14:15:22Z"    },    "token": "string"  }}

List personal access tokens GET

Lists your unrevoked tokens, newest first, without the token values. Expired tokens stay listed until revoked; compare `expires_at` with the current time.

Revoke a personal access token DELETE

Revokes the token immediately. Revoking a token that is already revoked also returns 204. A personal access token may call this only with its own ID, to revoke itself; any other ID returns 403.