# Mint an access token (the token is shown once) POST`/v1/tokens`[Token scope: `org:write`](https://developers.tasksmate.indrasol.com/guides/authentication/#scopes) Request **curl** ```bash curl -X POST "https://tasksmate-fdfsarhnf5gacfb7.eastus-01.azurewebsites.net/v1/tokens" \ -H "Authorization: Bearer $TASKSMATE_TOKEN" \ -H "Content-Type: application/json" \ -d '{"org_id":"string","name":"CI deploys","scopes":["tasks:write","projects:read"]}' ``` **Python** ```python from tasksmate import TasksMate tm = TasksMate() # reads TASKSMATE_TOKEN result = tm.tokens.create({"org_id": "string", "name": "CI deploys", "scopes": ["tasks:write", "projects:read"]}) print(result) ``` Response 200 ```json { "created_at": "2026-09-25T12:00:00Z", "created_by": "3f1c2a9e-0b7d-4c1e-9a55-2b8f0d6e4a10", "expires_at": "2026-12-31T00:00:00Z", "grant_type": "personal", "kind": "live", "name": "CI deploys", "org_id": "O0020", "principal_display": "ada", "principal_user_id": "3f1c2a9e-0b7d-4c1e-9a55-2b8f0d6e4a10", "scopes": [ "tasks:write" ], "status": "active", "token": "tm_live_Ab3xQ9eLr0v2Zk5n8WcHt1YpUo4MiGs7Fj6Da-_Bq0R", "token_id": "TK123456", "token_prefix": "tm_live_Ab3x", "updated_at": "2026-09-25T12:00:00Z", "use_count": 0 } ``` Mint a token. The response’s `token` is the only time it is ever shown — store it now. Yourself by default; `principal_user_id` = a service account of the org (owner / admin). The org’s policy applies (personal tokens allowed? expiry required? maximum lifetime?). ## Authorizations - **[bearerAuth](https://developers.tasksmate.indrasol.com/reference/#bearerauth)** - **[TasksMateToken](https://developers.tasksmate.indrasol.com/reference/#tasksmatetoken)** ## Request Bodyrequired application/json _TokenCreate_ The request body of `tokens.create`. object **org\_id** required _Org Id_ The organization the token belongs to (a token is org-bound) string \>= 1 characters **name** required _Name_ What the token is for string \>= 1 characters <= 100 characters **kind** _Kind_ `live` (tm\_live\_…) or `test` (tm\_test\_…: authenticates and reads, never writes) string default: live Allowed values: live test **scopes** required _Scopes_ Namespaced scopes: `tasks:read`, `tasks:write`, `projects:read`, `projects:write`, `teams:read`, `teams:write`, `org:read`, `org:write`, `webhooks:read`, `webhooks:write`, `admin`. `admin` implies every scope; `:write` implies `:read`. Array \>= 1 items **project\_ids** Any of: **Array** Array \>= 1 items **null** null **expires\_at** Any of: **string** string format: date-time **null** null **principal\_user\_id** Any of: **string** string format: uuid **null** null Example ```json { "org_id": "string", "name": "CI deploys", "kind": "live", "scopes": [ "tasks:write", "projects:read" ], "project_ids": [ "string" ], "expires_at": "2026-09-25T12:00:00Z", "principal_user_id": "3f1c2a9e-0b7d-4c1e-9a55-2b8f0d6e4a10" } ``` ## Responses ### 200 Successful Response application/json _TokenCreated_ Returned by `tokens.create` and `tokens.rotate`. object **token\_id** required _Token Id_ string **org\_id** required _Org Id_ string **principal\_user\_id** required _Principal User Id_ Who the token acts as string **principal\_display** Any of: **string** string **null** null **created\_by** required _Created By_ string **name** required _Name_ string **token\_prefix** required _Token Prefix_ The first 12 characters (`tm_live_ab12`) — the token itself is never shown again string **kind** required _Kind_ string Allowed values: live test **grant\_type** required _Grant Type_ string Allowed values: personal service\_account authorization\_code **client\_id** Any of: **string** string **null** null **scopes** required _Scopes_ Array **project\_ids** Any of: **Array** Array **null** null **expires\_at** Any of: **string** string format: date-time **null** null **last\_used\_at** Any of: **string** string format: date-time **null** null **use\_count** _Use Count_ integer 0 **status** required _Status_ string Allowed values: active revoked expired **revoked\_at** Any of: **string** string format: date-time **null** null **revoked\_by** Any of: **string** string **null** null **revoke\_reason** Any of: **string** string **null** null **rotated\_from** Any of: **string** string **null** null **created\_at** Any of: **string** string format: date-time **null** null **updated\_at** Any of: **string** string format: date-time **null** null **token** required _Token_ THE TOKEN — shown once, never stored (only its SHA-256 is). Send it as `Authorization: Bearer `. string Example ```json { "created_at": "2026-09-25T12:00:00Z", "created_by": "3f1c2a9e-0b7d-4c1e-9a55-2b8f0d6e4a10", "expires_at": "2026-12-31T00:00:00Z", "grant_type": "personal", "kind": "live", "name": "CI deploys", "org_id": "O0020", "principal_display": "ada", "principal_user_id": "3f1c2a9e-0b7d-4c1e-9a55-2b8f0d6e4a10", "scopes": [ "tasks:write" ], "status": "active", "token": "tm_live_Ab3xQ9eLr0v2Zk5n8WcHt1YpUo4MiGs7Fj6Da-_Bq0R", "token_id": "TK123456", "token_prefix": "tm_live_Ab3x", "updated_at": "2026-09-25T12:00:00Z", "use_count": 0 } ``` ### 400 Bad request — a query parameter outside what the operation accepts (`invalid-parameter`) application/problem+json _Problem_ An RFC 9457 problem details object — the body of every error response. `detail` is the human-readable explanation; `request_id` identifies the request for support. object **type** required `about:blank` or a `urn:tasksmate:problem:*` identifier string Allowed values: about:blank urn:tasksmate:problem:validation urn:tasksmate:problem:invalid-parameter urn:tasksmate:problem:precondition-failed urn:tasksmate:problem:idempotency-key-reused urn:tasksmate:problem:idempotency-key-in-flight urn:tasksmate:problem:idempotency-key-invalid urn:tasksmate:problem:rate-limit urn:tasksmate:problem:internal urn:tasksmate:problem:token-invalid urn:tasksmate:problem:token-expired urn:tasksmate:problem:token-revoked urn:tasksmate:problem:insufficient-scope urn:tasksmate:problem:test-token-read-only urn:tasksmate:problem:token-policy urn:tasksmate:problem:url-refused **title** required string **status** required integer **detail** required Human-readable explanation (a string; for a 422, the list of validation errors) **instance** required string **request\_id** required string **errors** Structured failures: validation errors, or `{loc, msg, allowed}` for a bad parameter Array object Example ```json { "type": "about:blank", "title": "Bad request", "status": 400, "detail": "…", "instance": "/v1/…", "request_id": "9b2f1c1e-8c1a-4a53-9f9e-0f5f1f2d7c11" } ``` ### 401 Missing or invalid bearer token application/problem+json _Problem_ An RFC 9457 problem details object — the body of every error response. `detail` is the human-readable explanation; `request_id` identifies the request for support. object **type** required `about:blank` or a `urn:tasksmate:problem:*` identifier string Allowed values: about:blank urn:tasksmate:problem:validation urn:tasksmate:problem:invalid-parameter urn:tasksmate:problem:precondition-failed urn:tasksmate:problem:idempotency-key-reused urn:tasksmate:problem:idempotency-key-in-flight urn:tasksmate:problem:idempotency-key-invalid urn:tasksmate:problem:rate-limit urn:tasksmate:problem:internal urn:tasksmate:problem:token-invalid urn:tasksmate:problem:token-expired urn:tasksmate:problem:token-revoked urn:tasksmate:problem:insufficient-scope urn:tasksmate:problem:test-token-read-only urn:tasksmate:problem:token-policy urn:tasksmate:problem:url-refused **title** required string **status** required integer **detail** required Human-readable explanation (a string; for a 422, the list of validation errors) **instance** required string **request\_id** required string **errors** Structured failures: validation errors, or `{loc, msg, allowed}` for a bad parameter Array object Example ```json { "type": "about:blank", "title": "Missing or invalid bearer token", "status": 401, "detail": "…", "instance": "/v1/…", "request_id": "9b2f1c1e-8c1a-4a53-9f9e-0f5f1f2d7c11" } ``` ### 403 Authenticated, but not allowed application/problem+json _Problem_ An RFC 9457 problem details object — the body of every error response. `detail` is the human-readable explanation; `request_id` identifies the request for support. object **type** required `about:blank` or a `urn:tasksmate:problem:*` identifier string Allowed values: about:blank urn:tasksmate:problem:validation urn:tasksmate:problem:invalid-parameter urn:tasksmate:problem:precondition-failed urn:tasksmate:problem:idempotency-key-reused urn:tasksmate:problem:idempotency-key-in-flight urn:tasksmate:problem:idempotency-key-invalid urn:tasksmate:problem:rate-limit urn:tasksmate:problem:internal urn:tasksmate:problem:token-invalid urn:tasksmate:problem:token-expired urn:tasksmate:problem:token-revoked urn:tasksmate:problem:insufficient-scope urn:tasksmate:problem:test-token-read-only urn:tasksmate:problem:token-policy urn:tasksmate:problem:url-refused **title** required string **status** required integer **detail** required Human-readable explanation (a string; for a 422, the list of validation errors) **instance** required string **request\_id** required string **errors** Structured failures: validation errors, or `{loc, msg, allowed}` for a bad parameter Array object Example ```json { "type": "about:blank", "title": "Authenticated, but not allowed", "status": 403, "detail": "…", "instance": "/v1/…", "request_id": "9b2f1c1e-8c1a-4a53-9f9e-0f5f1f2d7c11" } ``` ### 404 Not found application/problem+json _Problem_ An RFC 9457 problem details object — the body of every error response. `detail` is the human-readable explanation; `request_id` identifies the request for support. object **type** required `about:blank` or a `urn:tasksmate:problem:*` identifier string Allowed values: about:blank urn:tasksmate:problem:validation urn:tasksmate:problem:invalid-parameter urn:tasksmate:problem:precondition-failed urn:tasksmate:problem:idempotency-key-reused urn:tasksmate:problem:idempotency-key-in-flight urn:tasksmate:problem:idempotency-key-invalid urn:tasksmate:problem:rate-limit urn:tasksmate:problem:internal urn:tasksmate:problem:token-invalid urn:tasksmate:problem:token-expired urn:tasksmate:problem:token-revoked urn:tasksmate:problem:insufficient-scope urn:tasksmate:problem:test-token-read-only urn:tasksmate:problem:token-policy urn:tasksmate:problem:url-refused **title** required string **status** required integer **detail** required Human-readable explanation (a string; for a 422, the list of validation errors) **instance** required string **request\_id** required string **errors** Structured failures: validation errors, or `{loc, msg, allowed}` for a bad parameter Array object Example ```json { "type": "about:blank", "title": "Not found", "status": 404, "detail": "…", "instance": "/v1/…", "request_id": "9b2f1c1e-8c1a-4a53-9f9e-0f5f1f2d7c11" } ``` ### 409 Conflict (a duplicate, or an `Idempotency-Key` still in flight) application/problem+json _Problem_ An RFC 9457 problem details object — the body of every error response. `detail` is the human-readable explanation; `request_id` identifies the request for support. object **type** required `about:blank` or a `urn:tasksmate:problem:*` identifier string Allowed values: about:blank urn:tasksmate:problem:validation urn:tasksmate:problem:invalid-parameter urn:tasksmate:problem:precondition-failed urn:tasksmate:problem:idempotency-key-reused urn:tasksmate:problem:idempotency-key-in-flight urn:tasksmate:problem:idempotency-key-invalid urn:tasksmate:problem:rate-limit urn:tasksmate:problem:internal urn:tasksmate:problem:token-invalid urn:tasksmate:problem:token-expired urn:tasksmate:problem:token-revoked urn:tasksmate:problem:insufficient-scope urn:tasksmate:problem:test-token-read-only urn:tasksmate:problem:token-policy urn:tasksmate:problem:url-refused **title** required string **status** required integer **detail** required Human-readable explanation (a string; for a 422, the list of validation errors) **instance** required string **request\_id** required string **errors** Structured failures: validation errors, or `{loc, msg, allowed}` for a bad parameter Array object Example ```json { "type": "about:blank", "title": "Conflict (a duplicate, or an `Idempotency-Key` still in flight)", "status": 409, "detail": "…", "instance": "/v1/…", "request_id": "9b2f1c1e-8c1a-4a53-9f9e-0f5f1f2d7c11" } ``` ### 412 `If-Match` does not match the current `ETag` application/problem+json _Problem_ An RFC 9457 problem details object — the body of every error response. `detail` is the human-readable explanation; `request_id` identifies the request for support. object **type** required `about:blank` or a `urn:tasksmate:problem:*` identifier string Allowed values: about:blank urn:tasksmate:problem:validation urn:tasksmate:problem:invalid-parameter urn:tasksmate:problem:precondition-failed urn:tasksmate:problem:idempotency-key-reused urn:tasksmate:problem:idempotency-key-in-flight urn:tasksmate:problem:idempotency-key-invalid urn:tasksmate:problem:rate-limit urn:tasksmate:problem:internal urn:tasksmate:problem:token-invalid urn:tasksmate:problem:token-expired urn:tasksmate:problem:token-revoked urn:tasksmate:problem:insufficient-scope urn:tasksmate:problem:test-token-read-only urn:tasksmate:problem:token-policy urn:tasksmate:problem:url-refused **title** required string **status** required integer **detail** required Human-readable explanation (a string; for a 422, the list of validation errors) **instance** required string **request\_id** required string **errors** Structured failures: validation errors, or `{loc, msg, allowed}` for a bad parameter Array object Example ```json { "type": "about:blank", "title": "`If-Match` does not match the current `ETag`", "status": 412, "detail": "…", "instance": "/v1/…", "request_id": "9b2f1c1e-8c1a-4a53-9f9e-0f5f1f2d7c11" } ``` ### 422 The body or query did not validate (`validation`), or an `Idempotency-Key` was reused application/problem+json _Problem_ An RFC 9457 problem details object — the body of every error response. `detail` is the human-readable explanation; `request_id` identifies the request for support. object **type** required `about:blank` or a `urn:tasksmate:problem:*` identifier string Allowed values: about:blank urn:tasksmate:problem:validation urn:tasksmate:problem:invalid-parameter urn:tasksmate:problem:precondition-failed urn:tasksmate:problem:idempotency-key-reused urn:tasksmate:problem:idempotency-key-in-flight urn:tasksmate:problem:idempotency-key-invalid urn:tasksmate:problem:rate-limit urn:tasksmate:problem:internal urn:tasksmate:problem:token-invalid urn:tasksmate:problem:token-expired urn:tasksmate:problem:token-revoked urn:tasksmate:problem:insufficient-scope urn:tasksmate:problem:test-token-read-only urn:tasksmate:problem:token-policy urn:tasksmate:problem:url-refused **title** required string **status** required integer **detail** required Human-readable explanation (a string; for a 422, the list of validation errors) **instance** required string **request\_id** required string **errors** Structured failures: validation errors, or `{loc, msg, allowed}` for a bad parameter Array object Example ```json { "type": "about:blank", "title": "The body or query did not validate (`validation`), or an `Idempotency-Key` was reused", "status": 422, "detail": "…", "instance": "/v1/…", "request_id": "9b2f1c1e-8c1a-4a53-9f9e-0f5f1f2d7c11" } ``` ### 429 An access token over its per-minute limit (`rate-limit`; see `Retry-After`) application/problem+json _Problem_ An RFC 9457 problem details object — the body of every error response. `detail` is the human-readable explanation; `request_id` identifies the request for support. object **type** required `about:blank` or a `urn:tasksmate:problem:*` identifier string Allowed values: about:blank urn:tasksmate:problem:validation urn:tasksmate:problem:invalid-parameter urn:tasksmate:problem:precondition-failed urn:tasksmate:problem:idempotency-key-reused urn:tasksmate:problem:idempotency-key-in-flight urn:tasksmate:problem:idempotency-key-invalid urn:tasksmate:problem:rate-limit urn:tasksmate:problem:internal urn:tasksmate:problem:token-invalid urn:tasksmate:problem:token-expired urn:tasksmate:problem:token-revoked urn:tasksmate:problem:insufficient-scope urn:tasksmate:problem:test-token-read-only urn:tasksmate:problem:token-policy urn:tasksmate:problem:url-refused **title** required string **status** required integer **detail** required Human-readable explanation (a string; for a 422, the list of validation errors) **instance** required string **request\_id** required string **errors** Structured failures: validation errors, or `{loc, msg, allowed}` for a bad parameter Array object Example ```json { "type": "about:blank", "title": "An access token over its per-minute limit (`rate-limit`; see `Retry-After`)", "status": 429, "detail": "…", "instance": "/v1/…", "request_id": "9b2f1c1e-8c1a-4a53-9f9e-0f5f1f2d7c11" } ``` ### 500 Unexpected server error — quote `request_id` application/problem+json _Problem_ An RFC 9457 problem details object — the body of every error response. `detail` is the human-readable explanation; `request_id` identifies the request for support. object **type** required `about:blank` or a `urn:tasksmate:problem:*` identifier string Allowed values: about:blank urn:tasksmate:problem:validation urn:tasksmate:problem:invalid-parameter urn:tasksmate:problem:precondition-failed urn:tasksmate:problem:idempotency-key-reused urn:tasksmate:problem:idempotency-key-in-flight urn:tasksmate:problem:idempotency-key-invalid urn:tasksmate:problem:rate-limit urn:tasksmate:problem:internal urn:tasksmate:problem:token-invalid urn:tasksmate:problem:token-expired urn:tasksmate:problem:token-revoked urn:tasksmate:problem:insufficient-scope urn:tasksmate:problem:test-token-read-only urn:tasksmate:problem:token-policy urn:tasksmate:problem:url-refused **title** required string **status** required integer **detail** required Human-readable explanation (a string; for a 422, the list of validation errors) **instance** required string **request\_id** required string **errors** Structured failures: validation errors, or `{loc, msg, allowed}` for a bad parameter Array object Example ```json { "type": "about:blank", "title": "Unexpected server error", "status": 500, "detail": "…", "instance": "/v1/…", "request_id": "9b2f1c1e-8c1a-4a53-9f9e-0f5f1f2d7c11" } ``` --- Source: https://developers.tasksmate.indrasol.com/reference/operations/tokenscreate/