On this page
Authentication
Paylias API supports two authentication methods: JWT tokens and API keys. The authentication method you should use depends on the type of resource you're accessing.
Authentication Methods Overview
JWT Token Authentication
- Used for organization-level administrative operations
- Short-lived tokens (7 days validity)
- Requires admin user credentials
- Set via
Authorization: Bearer <token>header
API Key Authentication
- Used for operational resources and transactions
- Long-lived access tokens with fine-grained permissions
- Linked to specific namespaces
- Set via
X-Sfpy-Api-Key: <api_key>header - Requires
X-Partner-IDheader set to namespace ID
Resource-specific Authentication
Resources requiring JWT Authentication
The following resources require JWT token authentication:
| Resource Type | Description | Authentication Header |
|---|---|---|
| Organization | Business entity management | Authorization: Bearer <jwt_token> |
| Domain | Business function groupings | Authorization: Bearer <jwt_token> |
| Accounts | User account management | Authorization: Bearer <jwt_token> |
| Validations | Verification processes | Authorization: Bearer <jwt_token> |
| API Keys | API credential management | Authorization: Bearer <jwt_token> |
| Webhooks | Event notification endpoints | Authorization: Bearer <jwt_token> |
Example JWT request:
curl -X GET https://production.oysterapi.net/api/v1/csp/organization \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
Resources requiring API Key Authentication
The following resources require API key authentication:
| Resource Type | Description | Authentication Headers |
|---|---|---|
| Customers | End-user management | X-Sfpy-Api-Key + X-Partner-ID |
| Payments | Payment processing | X-Sfpy-Api-Key + X-Partner-ID |
| Submissions | Application processing | X-Sfpy-Api-Key + X-Partner-ID |
| Admissions | Admission management | X-Sfpy-Api-Key + X-Partner-ID |
| Submission Tasks | Submission workflows | X-Sfpy-Api-Key + X-Partner-ID |
| Admission Tasks | Admission workflows | X-Sfpy-Api-Key + X-Partner-ID |
| Transactions | Financial operations | X-Sfpy-Api-Key + X-Partner-ID |
Example API Key request:
curl -X GET https://production.oysterapi.net/api/v1/csp/customer \
-H "X-Sfpy-Api-Key: sfpy_key_123..." \
-H "X-Partner-ID: part_456..."
Error Handling
Common authentication errors:
| Status Code | Description | Solution |
|---|---|---|
| 401 | Invalid or expired JWT token | Refresh token or re-authenticate |
| 401 | Invalid API key | Verify key or generate new one |
| 401 | Missing Partner ID | Include X-Partner-ID header |