API Tokens

API tokens allow you to authenticate requests to the Pipeback API. You can create multiple tokens for different integrations and manage their lifecycle through the Pipeback dashboard.

Managing Tokens

All API token management happens in your Pipeback dashboard at Settings » API.

Creating a Token

To create a new API token:

Navigate to Settings » API
Click Create Token
Enter a descriptive name for your token
Choose an expiration period (optional)
Click Create Token

Your token will be displayed only once. Make sure to copy and store it securely.

Token Creation Response

{
  "token": "a0357fce-ad13-49de-ab39-91d94945d390|AY0Rspcu6NgE7ExjVxAskzrmAAPpL3fVlBLoiIcd916f7019",
  "access_token": {
    "id": "a0357fce-ad13-49de-ab39-91d94945d390",
    "name": "Production API",
    "abilities": ["*"],
    "last_used_at": null,
    "expires_at": "2030-10-26 00:00:00",
    "created_at": "2025-10-26 22:06:19",
    "status": "active"
  }
}

Token Expiration Options

You can set tokens to expire automatically after a specific period:

Name
Never expires
Type
default
Description
Token remains valid indefinitely until manually revoked
Name
1 day
Description
Token expires 24 hours after creation
Name
1 week
Description
Token expires 7 days after creation
Name
1 month
Description
Token expires 30 days after creation
Name
1 year
Description
Token expires 365 days after creation
Name
3 years
Description
Token expires 3 years after creation
Name
5 years
Description
Token expires 5 years after creation

Token Status

Each token has a status that indicates its current state:

Name
active
Type
string
Description
The token is valid and can be used to authenticate API requests
Name
expired
Type
string
Description
The token has passed its expiration date and can no longer be used

Expired tokens are automatically rejected when used for authentication. You'll need to create a new token to regain access.

Using Your Token

Once you have your API token, include it in the Authorization header along with your x-workspace-id header in all API requests.

You can find your workspace ID in Settings » API.

Example request with authentication

curl https://api.pipeback.com/app/contacts \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "x-workspace-id: YOUR_WORKSPACE_ID"

Remember: Both Authorization and x-workspace-id headers are required for all API requests.

Revoking Tokens

You can revoke a token at any time to immediately invalidate it:

Navigate to Settings » API
Find the token you want to revoke
Click the menu icon (⋯)
Select Revoke
Confirm the action

Warning: Revoking a token is permanent and cannot be undone. Any integrations using this token will immediately lose access to the API.

Best Practices

Name
Use descriptive names
Description
Name your tokens based on where they'll be used (e.g., "Production Server", "GitHub Actions", "Mobile App")
Name
Set appropriate expiration
Description
Use shorter expiration periods for temporary integrations and longer periods for production systems
Name
Store securely
Description
Never commit tokens to version control. Use environment variables or secret management systems
Name
Rotate regularly
Description
Create new tokens and revoke old ones periodically, especially for long-lived tokens
Name
Monitor usage
Description
Check the "Last Used" field to identify unused or potentially compromised tokens
Name
Revoke immediately
Description
If a token is compromised or no longer needed, revoke it immediately

Security Considerations

Never share tokens: Each integration should have its own token
Use HTTPS only: Always use HTTPS when making API requests with tokens
Environment variables: Store tokens in environment variables, not in code
Principle of least privilege: Create separate tokens for different purposes
Monitor activity: Regularly review which tokens are being used and when

If you suspect a token has been compromised, revoke it immediately and create a new one.