> 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. # Authorization SignalWire REST APIs support two authentication methods: **Basic Authentication** and **Bearer Authentication**. Basic Authentication takes either a Project's credentials or a [Personal access token](#personal-access-tokens). Each endpoint specifies which method and credential it accepts. ## Basic authentication [Basic Authentication](https://swagger.io/docs/specification/v3_0/authentication/basic-authentication/) is the standard method for authenticating with SignalWire REST APIs, using your **Project ID** and **API Token**. ### How it works Include an `Authorization` header with each request: ``` Authorization: Basic ``` To build the `credentials` string: 1. Join your Project ID and API Token with a colon: `ProjectID:APIToken` 2. [Base64](https://developer.mozilla.org/en-US/docs/Glossary/Base64) encode the result #### Example Given the Project ID `a1b2c3d4-e5f6-7890-abcd-ef1234567890` and API Token `swapi_0123456789ab0123456789ab0123456789ab`: ```bash # In the format username:password a1b2c3d4-e5f6-7890-abcd-ef1234567890:swapi_0123456789ab0123456789ab0123456789ab # Base64 encoded: YTFiMmMzZDQtZTVmNi03ODkwLWFiY2QtZWYxMjM0NTY3ODkwOnN3YXBpXzAxMjM0NTY3ODlhYjAxMjM0NTY3ODlhYjAxMjM0NTY3ODlhYg== # Full header: Authorization: Basic YTFiMmMzZDQtZTVmNi03ODkwLWFiY2QtZWYxMjM0NTY3ODkwOnN3YXBpXzAxMjM0NTY3ODlhYjAxMjM0NTY3ODlhYjAxMjM0NTY3ODlhYg== ``` API tokens created earlier begin with `PT` and are 50 characters long. Both formats authenticate the same way, so treat a token as an opaque string rather than matching it against a pattern. See [API credentials](/docs/platform/your-signalwire-api-space) for details on token format. ### Finding your credentials Your Project ID and API Tokens are available in the [SignalWire Dashboard](/docs/platform/your-signalwire-api-space). In the Dashboard, open **API Credentials**. Copy the **Project ID**, then reveal and copy an existing API token or select **+ New** to create one. ### API token scopes Tokens can be scoped to limit API access. Select scopes when creating or editing a token in the Dashboard. Getting a `401 Unauthorized`? Check that your token has the required scope. Manage scopes in the [SignalWire Dashboard](/docs/platform/your-signalwire-api-space). ### cURL examples **`cURL`** ```bash title="cURL" # With base64-encoded credentials curl https://{Your_Space_Name}.signalwire.com/api/laml/2010-04-01/Accounts/{YourProjectId}/Calls \ -H 'Authorization: Basic YTFiMmMzZDQtZTVmNi03ODkwLWFiY2QtZWYxMjM0NTY3ODkwOnN3YXBpXzAxMjM0NTY3ODlhYjAxMjM0NTY3ODlhYjAxMjM0NTY3ODlhYg==' # Encoded inline using the Bash pipe operator curl https://{Your_Space_Name}.signalwire.com/api/laml/2010-04-01/Accounts/{YourProjectId}/Calls \ -H "Authorization: Basic $(echo -n "YourProjectId:YourApiToken" | base64)" # Encoded inline with cURL's -u flag curl https://{Your_Space_Name}.signalwire.com/api/laml/2010-04-01/Accounts/{YourProjectId}/Calls \ -u YourProjectId:YourApiToken ``` --- ## Personal access tokens A Personal access token (PAT) authenticates you as a person rather than as a Project. It carries your role in the Space, owner or admin, instead of a Project's scopes, so it can do what no Project API token can: administer the Space itself, and create or delete root Projects. Create one from your user menu in the Dashboard, on the **Personal Access Tokens** page. The token is prefixed `pat_`, has no scopes, and can't be created through the API. ### How it works Send a Personal access token with Basic Authentication, leaving the username empty and using the token as the password: ``` Authorization: Basic ``` **`cURL`** ```bash title="cURL" curl https://{Your_Space_Name}.signalwire.com/api/space \ -u ":pat_your_personal_access_token" ``` ### Where it's accepted * The [Space Administration API](/docs/apis/rest/space/get-space) under `/api/space` accepts only a Personal access token. It manages the Space name, geographic permissions, members and their Project access, balance, billing, and payment methods. * The [Projects](/docs/apis/rest/projects/list-projects) and [Project Tokens](/docs/apis/rest/project-tokens/create-token) APIs accept either credential on the same path; the `pat_` prefix decides which rules apply. With a Personal access token you can create and delete root Projects, and create an API token for a Project named in the request. ### Scope A Personal access token acts only on the Space whose subdomain you call. Its holder must be an owner or admin of that Space; an employee or guest membership is rejected. On the Projects and Project Tokens APIs it reaches only the Projects its holder is enabled for, plus their Subprojects, and any other Project ID returns `404`. Authorization failures return `401 Unauthorized` with the plain text body `Unauthorized`, not `403`, so a "wrong role" and a bad token look the same. A Space that hasn't yet verified a phone number receives `401` with a JSON body `{"message": "Please validate a phone number to access your account."}` on every `/api/space` endpoint. --- ## Bearer authentication [Bearer Authentication](https://swagger.io/docs/specification/v3_0/authentication/bearer-authentication/) passes a token in the `Authorization` header. Use this for client-side calls where you can't safely expose your API credentials. ### How it works Include the token in an `Authorization` header: ``` Authorization: Bearer ``` Bearer tokens are short-lived and scoped to specific permissions, unlike API credentials which don't expire. ### Token types #### [Subscriber](/docs/platform/subscribers) Access Token (SAT) SATs authenticate end users in Fabric applications, letting client apps make API calls on behalf of a [subscriber](/docs/platform/subscribers). **How to obtain:** Call the Create Subscriber Token endpoint using Basic Auth. ```bash curl -X POST https://your-space.signalwire.com/api/fabric/subscribers/tokens \ -H 'Authorization: Basic ' \ -H 'Content-Type: application/json' \ -d '{ "reference": "user@example.com", "expire_at": 1725513600 }' ``` **Use case:** Client apps connecting to Fabric services, such as listing resource addresses. #### Guest Token Guest Tokens grant limited, temporary access without full subscriber privileges. They're created from an existing SAT and restricted to specific Fabric addresses. **How to obtain:** Call the Create Guest Embed Token endpoint using a SAT. ```bash curl -X POST https://your-space.signalwire.com/api/fabric/guests/tokens \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ -d '{ "allowed_addresses": ["c22d24f6-5a26-4f53-8008-b29530339efa"] }' ``` **Use case:** Click-to-call widgets, guest access, or anywhere you need temporary access. ### Token lifecycle Bearer tokens expire. Once they do, requests return `401 Unauthorized` and you'll need a fresh token. To keep a session alive without re-authenticating, call the Refresh Subscriber Token endpoint before expiration. ### cURL example **`cURL`** ```bash title="cURL" curl https://your-space.signalwire.com/api/fabric/addresses \ -H 'Authorization: Bearer ' ``` With a SAT token: **`cURL`** ```bash title="cURL" curl https://your-space.signalwire.com/api/fabric/addresses \ -H 'Authorization: Bearer eyJhbGciOiJkaXIiLCJlbmMiOiJBMjU2R0NNIiwiY2giOiJwdWMuc2lnbmFsd2lyZS5jb20iLCJ0eXAiOiJTQVQifQ...' ``` --- ## Security best practices 1. **Keep API credentials server-side.** Use Bearer tokens for client applications. Treat a Personal access token as you would your own login: it carries your Space role, and it belongs in automation you run yourself. 2. **Set short token lifetimes** to reduce risk if a token leaks. 3. **Scope tokens narrowly**—only grant what's needed. 4. **Always use HTTPS.** Plain HTTP requests will fail. 5. **Rotate API tokens periodically** from your Dashboard.