API Authentication

Waqti uses token-based authentication for all API requests. This guide explains how to authenticate and manage your API tokens.

Overview

All API endpoints require authentication using a Bearer token. Tokens are scoped to your tenant and can be created, managed, and revoked from the Settings panel.

Getting an API Token

Via Settings UI

1. Navigate to Settings → API Settings
2. Click Generate New Token
3. Enter a descriptive name for the token (e.g., "ERP Integration")
4. Select the appropriate permissions/scopes
5. Click Create
6. Important: Copy the token immediately. It will only be shown once.

Via API (if you have an existing token)

POST /api/v1/tokens
Authorization: Bearer {existing_token}
Content-Type: application/json

{
  "name": "New Token Name",
  "abilities": ["read", "write"]
}

Using Your Token

Include the token in the Authorization header of every request:

curl -X GET "https://acme.waqti.sa/api/v1/purchase-orders" \
  -H "Authorization: Bearer 3|a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0" \
  -H "Accept: application/json"

Token Scopes/Abilities

Tokens can be created with limited abilities:

Ability	Description
read	Read-only access to all resources
write	Create and update resources
delete	Delete resources
approve	Approve/reject items
admin	Full administrative access

Example: Read-Only Token

{
  "name": "Reporting Integration",
  "abilities": ["read"]
}

Example: Full Access Token

{
  "name": "ERP Sync",
  "abilities": ["read", "write", "delete"]
}

Token Security Best Practices

Security Notice

API tokens grant access to your procurement data. Follow these best practices:

1. Never share tokens - Each integration should have its own token
2. Use minimum permissions - Only grant abilities actually needed
3. Rotate regularly - Regenerate tokens every 90 days
4. Audit usage - Review token activity in API logs
5. Revoke unused tokens - Delete tokens for decommissioned integrations

Revoking Tokens

Via Settings UI

1. Go to Settings → API Settings
2. Find the token in the list
3. Click Revoke
4. Confirm the action

Via API

DELETE /api/v1/tokens/{token_id}
Authorization: Bearer {admin_token}

Rate Limiting

API requests are rate limited based on your subscription plan:

Plan	Requests/Minute	Requests/Day
Professional	60	10,000
Enterprise	120	50,000
Ultimate	300	Unlimited

When you exceed the rate limit, you'll receive a 429 Too Many Requests response with headers indicating when you can retry:

HTTP/1.1 429 Too Many Requests
Retry-After: 30
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1640000000

Error Responses

401 Unauthorized

Missing or invalid token:

{
  "message": "Unauthenticated.",
  "errors": {
    "token": ["Invalid or expired token"]
  }
}

403 Forbidden

Token doesn't have required ability:

{
  "message": "This action is unauthorized.",
  "errors": {
    "ability": ["Token does not have 'write' ability"]
  }
}

Token Expiration

By default, tokens don't expire. However, you can set an expiration when creating:

{
  "name": "Temporary Access",
  "abilities": ["read"],
  "expires_at": "2025-03-01T00:00:00Z"
}

Testing Your Token

Use this endpoint to verify your token is valid:

curl -X GET "https://acme.waqti.sa/api/v1/me" \
  -H "Authorization: Bearer 3|a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0" \
  -H "Accept: application/json"

Expected response:

{
  "data": {
    "tenant_id": "acme-corp",
    "tenant_name": "ACME Corporation",
    "token_name": "ERP Integration",
    "abilities": ["read", "write"],
    "last_used_at": "2025-01-15T10:30:00Z"
  }
}