Authentication

The On Me API authenticates every request with a secret API key. Your key belongs to your organization, and anything you do with it, including spending your balance, happens on your organization's behalf.

Get an API key

Org admins create and manage keys in the business portal, under Account → Developers.

1. Make sure your organization has a business portal account. If it doesn't, sign up first.
2. Fund your balance under Billing. Every order you create through the API is paid for from it.
3. Open Account → Developers and select Create key. Give the key a name that says where it's used, such as "Production server".

If your organization doesn't have API access yet, the Developers page shows a Request access button instead. We email your organization's admins as soon as it's on.

Keys start with omk-. Keys we issued before self-serve keys launched start with sk_, and they keep working.

Authenticate requests

Send your key as a bearer token in the Authorization header of every request:

Authorization: Bearer omk-...

The examples in these docs read the key from an environment variable called ONME_API_KEY. List the categories to check that yours works:

curl https://api.onme.com/v1/categories \
  -H "Authorization: Bearer $ONME_API_KEY"

A 200 with a list of categories means you're in. A 401 means the key is missing or wrong; the error's code tells you which (see authentication errors).

Every endpoint needs a key except two: GET /v1/health and GET /v1/openapi.json, which serves the API's OpenAPI document.

Keep your key safe

Your key can spend your organization's balance, so treat it like a password to your bank account.

• Use it only on your servers. Never put it in a browser, a mobile app or anything else you ship to users, where anyone can extract it. If your frontend needs to send a gift, have it call your backend, and have your backend call On Me.
• Keep it out of source control. Load it from a secrets manager or an environment variable, never from a file you commit.
• Keep it out of logs. Make sure your HTTP client and error tracker redact the Authorization header.

Your organization can have up to 10 active keys. Use a separate key for each system that calls the API, so you can revoke one without touching the others. Every key has full access to all of your organization's orders and gifts. There are no read-only or per-endpoint keys yet, so limit who and what can read them.

Rotate or revoke a key

To rotate a key without downtime:

1. Create a new key under Account → Developers.
2. Deploy it everywhere the old key is used.
3. Watch the old key's Last used time on the Developers page. Once it stops changing, nothing is using it any more.
4. Revoke the old key.

If you think a key has leaked, revoke it straight away. Revocation takes effect immediately: the next request with that key fails with api_key_revoked. It's also permanent, so create a new key to carry on with.

Every admin in your organization gets an email whenever a key is created or revoked.

Sandbox

Sandbox keys start with omk-sandbox-. Create one by switching the business portal to Sandbox mode, then adding a key under Account → Developers.

There is no separate sandbox URL. You call the same base URL either way and your key decides which environment serves the request, so moving to production means swapping the key and changing nothing else. A sandbox key spends a sandbox balance, reaches no real recipient, and charges no card.

Keys are not interchangeable between environments, and that is enforced rather than assumed: a key that somehow reaches the wrong environment is refused with api_key_environment_mismatch rather than being served. You should never see it.

See Testing in the sandbox for the recipient addresses that let you choose what happens to a gift.

The Try it button in the API reference sends its requests to the sandbox, so it is safe to click around.

Authentication errors

When we can't authenticate a request, you get one of these errors. None of them change anything, so once you've fixed the cause it's safe to send the same request again.