> Fetch clean Markdown by appending `.md` to any page URL under https://signalwire.com/docs or requesting it with the HTTP header `Accept: text/markdown`. The root index at https://signalwire.com/docs/llms.txt lists the available documentation indexes. # create > Create a new API token for the project. ### tokens.create Create a new API token for the project. ### Schema ```yaml openapi: 3.1.0 info: title: API version: 1.0.0 paths: /api/project/tokens: post: operationId: subpackageProjectTokens_create_token summary: Create API token description: >- Creates a project API token for server-side authentication to SignalWire REST APIs, with only the permission categories supplied in the request. Use it when a backend service needs durable project credentials; client applications should receive a service-specific token such as a [Chat Token](/docs/apis/rest/chat-tokens/create-chat-token), [PubSub Token](/docs/apis/rest/pubsub/create-token), [Room Token](/docs/apis/rest/video/room-tokens/create-room-token), or [Subscriber Token](/docs/apis/rest/subscribers/tokens/create-subscriber-token) instead. The token remains usable until you delete it or remove required permissions. The Compatibility API exposes the same project tokens through its account-scoped route. Use [Generate a new API Token](/docs/compatibility-api/rest/tokens/create-token) for that request format. The response is the only place the token secret is returned. Store it securely; no later request, including [Update API token](/docs/apis/rest/project-tokens/update-token), can read it back. With a project API token, the new token belongs to the authenticated project, or to one of its subprojects when `subproject_id` is given; `project_id` is ignored. With a [Personal access token](/docs/apis/authorization#personal-access-tokens), `project_id` is required and names the project the token is created for, which is how a root project created with [Create a project](/docs/apis/rest/projects/create-subproject) gets its first credential. #### Permissions With a project API token, the token must have the following scope(s) enabled to make a successful request: _Management_. With a [Personal access token](/docs/apis/authorization#personal-access-tokens) there are no scopes. The token holder must be an owner or admin of the space, and the request reaches only the projects the holder is enabled for, plus their subprojects. [Learn more about API scopes](/docs/platform/your-signalwire-api-space). #### Token Permissions You must set the functions allowed by this API Token by selecting which types of requests this API Token is allowed to make. Valid options are: calling, chat, datasphere, fax, management, messaging, numbers, pubsub, storage, tasking, and video tags: - subpackage_projectTokens responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/Project.CreateTokenResponse' '401': description: Access is unauthorized. content: application/json: schema: $ref: '#/components/schemas/Types.StatusCodes.StatusCode401' '422': description: The request contains invalid parameters. See errors for details. content: application/json: schema: $ref: '#/components/schemas/PubSub.PubSubToken422Error' '500': description: An internal server error occurred. content: application/json: schema: $ref: '#/components/schemas/Types.StatusCodes.StatusCode500' requestBody: content: application/json: schema: $ref: '#/components/schemas/Project.CreateTokenRequest' tags: - name: subpackage_projectTokens servers: - url: https://%7BYour_Space_Name%7D.signalwire.com description: SignalWire API components: schemas: Project.TokenPermission: type: string enum: - calling - chat - datasphere - fax - management - messaging - numbers - pubsub - storage - tasking - video description: Valid permission types for API tokens. title: Project.TokenPermission uuid: type: string format: uuid description: Universal Unique Identifier. title: uuid Project.CreateTokenRequest: type: object properties: name: type: string description: The name representing the API token. permissions: type: array items: $ref: '#/components/schemas/Project.TokenPermission' description: >- The permissions you would like to enable for this token. Valid permissions are calling, chat, datasphere, fax, management, messaging, numbers, pubsub, storage, tasking, and video project_id: $ref: '#/components/schemas/uuid' description: >- Personal access token only. The project to create the token for. Required with a Personal access token and must name a project the token holder can reach (`invalid_project_id`). Ignored with a project API token, which creates the token on its own project. subproject_id: $ref: '#/components/schemas/uuid' description: >- The unique identifier of the subproject you would like to create a token for. The subproject passed must be a child of the project used to authenticate the request, or of `project_id` when authenticating with a Personal access token. required: - name - permissions description: Request body for creating a new API Token. title: Project.CreateTokenRequest Project.CreateTokenResponse: type: object properties: id: $ref: '#/components/schemas/uuid' description: The ID of the API Token. name: type: string description: The name of the API Token. permissions: type: array items: $ref: '#/components/schemas/Project.TokenPermission' description: The permissions enabled for this token. token: type: string description: >- The API token that can be used along with the project ID for basic authentication. It is returned only in this response and cannot be retrieved again; store it securely. required: - id - name - permissions - token title: Project.CreateTokenResponse TypesStatusCodesStatusCode401Error: type: string enum: - Unauthorized title: TypesStatusCodesStatusCode401Error Types.StatusCodes.StatusCode401: type: object properties: error: $ref: '#/components/schemas/TypesStatusCodesStatusCode401Error' required: - error description: Access is unauthorized. title: Types.StatusCodes.StatusCode401 Types.StatusCodes.RestApiErrorItem: type: object properties: type: type: string description: The category of error. code: type: string description: A specific error code. message: type: string description: A description of what caused the error. attribute: type: - string - 'null' description: The request parameter that caused the error, if applicable. url: type: string description: A link to documentation about this error. required: - type - code - message - url description: Details about a specific error. title: Types.StatusCodes.RestApiErrorItem PubSub.PubSubToken422Error: type: object properties: errors: type: array items: $ref: '#/components/schemas/Types.StatusCodes.RestApiErrorItem' description: List of validation errors. required: - errors description: The request contains invalid parameters. See errors for details. title: PubSub.PubSubToken422Error TypesStatusCodesStatusCode500Error: type: string enum: - Internal Server Error title: TypesStatusCodesStatusCode500Error Types.StatusCodes.StatusCode500: type: object properties: error: $ref: '#/components/schemas/TypesStatusCodesStatusCode500Error' required: - error description: An internal server error occurred. title: Types.StatusCodes.StatusCode500 ``` ## **Response Example** ### Response (200) ```json { "id": "ea14556a-984f-11ee-b9d1-0242ac120002", "name": "John Doe's Token", "permissions": [ "calling", "fax", "messaging" ], "token": "swapi_0123456789ab0123456789ab0123456789ab" } ``` ## **Example** ```typescript {9} import { RestClient } from "@signalwire/sdk"; const client = new RestClient({ project: "your-project-id", token: "your-api-token", host: "your-space.signalwire.com" }); const token = await client.project.tokens.create({ name: "ci-token" }); console.log("Token:", token["token"]); console.log("ID:", token.id); ``` > Create a new API token for the project.