Skip to main content
Syncgram Pay supports two authentication methods:
MethodUse caseFormat
API keyServer-to-server integrationsAuthorization: Bearer sk_...
JWT tokenDashboard sessions and user-facing flowsAuthorization: Bearer eyJ...
For programmatic integrations, always use an API key.

​
API keys

API keys are long-lived credentials scoped to your organization. They are the recommended method for authenticating server-side API calls.

​
Getting an API key

You can create an API key from your dashboard or via the API. You need a valid user session (JWT token) to create a key. 
curl -X POST https://api.syncgrampay.com/api/v1/auth/api-keys \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your_access_token>" \
  -d '{
    "key_name": "Production Server"
  }'
Response:
{
  "success": true,
  "data": {
    "api_key_id": "ak_01j...",
    "key": "sk_live_01j...",
    "key_name": "Production Server",
    "created_at": "2024-01-15T10:00:00Z",
    "expires_at": null
  }
}
The API key is shown only once at creation. Store it immediately in a secrets manager or environment variable. If you lose it, you must revoke and recreate it.

​
Using the API key

Pass your API key as a Bearer token in the Authorization header of every request. 
curl https://api.syncgrampay.com/api/v1/payments/payins \
  -H "Authorization: Bearer sk_live_01j..."
Your API key must start with sk_. Requests using a key that does not include this prefix will be rejected.

​
Test vs live keys

Your API key is automatically scoped to the environment your organization is currently in:
  • Test keys — Used while your account is in test mode. Prefixed sk_test_. No real money moves.
  • Live keys — Used once your account is verified and live payments are enabled. Prefixed sk_live_.
To switch environments, revoke your current key and create a new one after changing your organization’s environment setting.

​
One active key per organization

You can have at most one active API key per organization at a time. If you need to rotate your key:
  1. Create a new key — this will fail if an active key already exists.
  2. Revoke the existing key first, then create the new one.

​
Revoking a key

curl -X POST https://api.syncgrampay.com/api/v1/auth/api-keys/<api_key_id>/revoke \
  -H "Authorization: Bearer <your_access_token>"
Revoked keys are immediately invalidated. Any in-flight requests using the revoked key will return a 401 Unauthorized error.

​
JWT tokens

JWT tokens are short-lived credentials issued after a successful user login. They are used by the Syncgram Pay dashboard and are suitable for user-facing flows, but are not recommended for server-to-server integrations due to their short lifetime (15 minutes).

​
Obtaining a token

Login is a two-step process: Step 1 — Submit credentials: 
curl -X POST https://api.syncgrampay.com/api/v1/auth/login/init
# Use the returned token in the login request below

curl -X POST https://api.syncgrampay.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "you@example.com",
    "password": "yourpassword",
    "login_token": "<token_from_init>"
  }'
Step 2 — Verify the 2FA challenge: 
curl -X POST https://api.syncgrampay.com/api/v1/auth/login/2fa/verify \
  -H "Content-Type: application/json" \
  -d '{
    "challenge_id": "ch_01j...",
    "code": "847291",
    "code_type": "primary"
  }'
This returns an access_token (15-minute lifetime) and a refresh_token (30-day lifetime).

​
Refreshing a token

When your access token expires, exchange the refresh token for a new one: 
curl -X POST https://api.syncgrampay.com/api/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "refresh_token": "rt_01j..."
  }'

{
  "success": true,
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refresh_token": "rt_01j_new..."
  }
}
Refresh tokens are rotated on every use. The old refresh token is invalidated when a new one is issued.

​
Error responses

If your request is not authenticated correctly, the API returns one of the following errors:

​
401 Unauthorized

Returned when no token is provided, the token is invalid, or the token has expired. 
{
  "success": false,
  "detail": "Invalid credentials",
  "error_code": "UNAUTHORIZED"
}
Common causes:
  • Missing Authorization header
  • Expired access token (use /auth/refresh to get a new one)
  • Revoked API key

​
403 Forbidden

Returned when the token is valid but the request is not permitted for your account or role. 
{
  "success": false,
  "detail": "You do not have permission to perform this action",
  "error_code": "FORBIDDEN"
}
Common causes:
  • Attempting to access a resource that belongs to a different organization
  • Your account has not completed onboarding required for this action

​
Security best practices

  • Store API keys in environment variables, never in source code or version control.
  • Rotate your API key periodically by revoking the old key and creating a new one.
  • Use the test environment (sk_test_ keys) during development.
  • Never share your API key publicly or log it in application output.