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. Each endpoint specifies which method and credential it accepts.

Basic 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 <credentials>

To build the credentials string:

1. Join your Project ID and API Token with a colon: ProjectID:APIToken
2. Base64 encode the result

Example

Given the Project ID a1b2c3d4-e5f6-7890-abcd-ef1234567890 and API Token swapi_0123456789ab0123456789ab0123456789ab:

# 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 for details on token format.

Finding your credentials

Your Project ID and API Tokens are available in the SignalWire Dashboard.

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.

cURL examples

# 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 <Base64(":pat_...")>

curl https://{Your_Space_Name}.signalwire.com/api/space \
     -u ":pat_your_personal_access_token"

Where it’s accepted

• The Space Administration API 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 and Project Tokens 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 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 <token>

Bearer tokens are short-lived and scoped to specific permissions, unlike API credentials which don’t expire.

Token types

Subscriber Access Token (SAT)

SATs authenticate end users in Fabric applications, letting client apps make API calls on behalf of a subscriber.

How to obtain: Call the Create Subscriber Token endpoint using Basic Auth.

curl -X POST https://your-space.signalwire.com/api/fabric/subscribers/tokens \
     -H 'Authorization: Basic <Base64(YourProjectID:YourAPIToken)>' \
     -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.

curl -X POST https://your-space.signalwire.com/api/fabric/guests/tokens \
     -H 'Authorization: Bearer <subscriber_access_token>' \
     -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 https://your-space.signalwire.com/api/fabric/addresses \
     -H 'Authorization: Bearer <token>'

With a SAT token:

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.