Skip to main content

Create an API Access Token

An access token is what lets a script, an integration, or a curl command call Oho's API on your behalf. It's the first thing you'll need when you start an API integration.

What you'll end up with

A token copied into your own secrets manager, and a clear idea of what it can reach — which is exactly what the account that created it can reach.

Before you start​

Read this first, because it decides which account you should be signed in as:

A token inherits the privileges of whoever creates it

A token has no permission set of its own. It can do whatever the account that created it can do — no more, no less. A token made by a Super Admin can read everything a Super Admin can.

So sign in as the account whose access the integration should have before you create it. A token made from a personal admin login is also tied to that person: it carries their name in the audit trail and stops working when their account is deactivated.

For a server-to-server integration that shouldn't depend on an individual, use an OAuth2 client instead.

You'll also need to be a Super Admin — the Manage Technical Setup privilege gates the whole Developer section, API Credentials included — and token authentication must be enabled for your tenant. If API Credentials doesn't appear under Settings → Developer, you don't have technical-setup access; ask your Oho administrator.

Step 1: Open API Credentials​

Go to Settings → Developer → API Credentials. The page is titled Manage API Credentials and it lists the tokens that already exist, with their name, description, expiry and owner. Access tokens and OAuth2 client credentials are both managed here — there is no separate page for them.

Step 2: Create the token​

Click Add credential, choose Personal Token under Access token, and fill in:

FieldWhat to put
Token NameA name that identifies it later — name the integration, not the person. Up to 50 characters
DescriptionOptional. Up to 500 characters
Expires in1 hour, 1 day, 1 month (the default), 3 months, or Never

The modal shows the exact expiry date under the dropdown as you choose.

Prefer a real expiry over Never. A token that can't expire is one you have to remember to retire; a dated one forces the rotation you'd want anyway. If you pick an expiry, diarise the rotation — a token expiring unnoticed looks exactly like an outage.

Click Create.

Step 3: Copy it now​

The token's value is shown once, on the screen immediately after creation, with a ready-made curl command beside it. Copy it straight into your secrets manager or environment.

There's no way to retrieve it later

Close that screen without copying and the value is gone — nothing in Oho can show it to you again. Your only option is to create a new token and revoke the lost one.

Never commit a token to source control, paste it into a ticket or shared document, or log it. Anyone holding it can act as the account that created it.

Step 4: Check it works​

curl -sS -o /dev/null -w "%{http_code}\n" "$OHO_BASE/workers?pageSize=1" \
  -H "Authorization: Bearer $OHO_TOKEN"   # expect 200

A 401 means the token is missing, malformed or expired. A 403 means the token is valid but the account behind it lacks access to that entity type — go back to Before you start.

Rotating and revoking​

Rotate by overlapping rather than swapping: issue the new token, roll it out everywhere, then revoke the old one. Both are valid at once, so nothing breaks mid-deploy. Revoke from the same Settings → Developer → API Credentials list.

Rotating a token has the full procedure, including how to sanity-check a new token before you roll it out.

Revoke immediately — don't wait for the rotation — if a token has been exposed, or when the person who created it leaves.