Authentication
Authenticate Workflow API requests with HTTP Basic using your PayMongo secret key and the required Organization-Id header.
The Workflow API uses the same authentication model as the rest of PayMongo: an HTTP Basic header carrying your secret key, plus the Organization-Id header that identifies the organization the request acts on.
Secret keys
Every Workflow API request authenticates with a PayMongo secret key. The key prefix decides whether the request runs in test mode (sk_test_...) or live mode (sk_live_...). Workflows, triggers, instances, and wait states are isolated between modes. A workflow created with a test key is invisible to a live key, and vice versa.
The Authorization header is built from your secret key followed by a colon, base64-encoded:
# Construct the token
echo -n "${YOUR_SECRET_KEY}:" | base64
# → e.g. c2tfdGVzdF9hYmMxMjM6The trailing colon is mandatory. Most HTTP clients build it automatically when you set the username to your secret key and leave the password empty.
Required headers
Every authenticated request must carry both headers below.
| Header | Required | Description |
|---|---|---|
Authorization | Yes | HTTP Basic. Username = your secret key (sk_test_... or sk_live_...); password = empty. |
Organization-Id | Yes | The PayMongo organization ID the request acts on. Must match the organization that owns the secret key. |
Content-Type | Yes | application/json for JSON request bodies, or text/plain when posting a YAML workflow definition. |
Livemode isolation
The key prefix determines livemode:
sk_live_...: live mode. Real money movement, real bank rails.sk_test_...: test mode. Sandbox; transfers do not move real funds.
Cross-livemode reads return 404 Not Found. A test-mode key cannot retrieve, list, or modify a live-mode workflow even when it knows the ID. The existence of the resource is not leaked across the boundary.
Authentication errors
| Code | HTTP | When it fires |
|---|---|---|
authentication_failed | 401 | The Authorization header is missing, malformed, or the key is invalid. |
missing_organization_header | 400 | The Authorization header is valid but the Organization-Id header is absent. |
organization_mismatch | 403 | The Organization-Id header does not match the organization tied to the secret key. |
livemode_mismatch | 403 | A request attempts to act on a resource in the opposite livemode (only surfaces on a small set of writes). |
The full error envelope shape is described in Validation and Errors.
Example
curl --request GET 'https://workflow-api.paymongo.com/v1/workflows' \
--header 'Authorization: Basic ${YOUR_BASIC_TOKEN}' \
--header 'Organization-Id: ${YOUR_ORG_ID}' \
--header 'Content-Type: application/json'A successful response is a JSON envelope of workflows. Any of the codes above will appear in the standard error envelope on failure.
Updated 3 days ago