Call the API from your app
Goal: Send the right token and headers so your app's calls are let in.
The address
Every route is under /ox-api/ on your workspace host:
https://openx.fathym.com/ox-api/<route>
The API Manager shows each endpoint's full address. The catalogue of the routes you may call is
GET /ox-api/openapi; add ?root=<an absolute URL> to have its paths written against another root, such as a
gateway in front of OpenX.
The headers
| Header | Value | When |
|---|---|---|
Authorization | Bearer <token> | Every call. Only this header is read; a token in the URL is refused, even beside a header |
x-oi-workspace | Your workspace id | Required with a token from an App Identity. Optional with any other token, but if you send it, it must name the token's own workspace |
Content-Type | application/json | When you send a JSON body |
Your workspace id is the ID shown in Workspace -> Settings. It is the same value that ends a workspace's
MCP address, /ox-api/mcp/w/<workspace id>.
The Calling with a directory token line in the API Manager carries x-oi-workspace, and so do the Code
Snippets of a card in Hybrid or App Identity mode (see API Explorer). Where
the window cannot read the workspace id, they show <YOUR_WORKSPACE_ID> for you to fill in. A call with an App
Identity token and no x-oi-workspace is refused with the plain 401.
Which token to send
What the workspace takes depends on its API mode, set in Secure your workspace API.
| Token | Where it comes from | Team | Hybrid | App Identity |
|---|---|---|---|---|
| A team API key | API Keys, or Authentication in the API Manager | Yes | Yes | No |
| A person's directory token | Your app signs the person in with a trusted App Identity and asks for the scope the API Manager shows | No | Yes | Yes |
| A job's directory token | The job's own client in your directory, with a certificate or a federated credential | No | Yes | Yes |
| A swapped job token | POST /ox-api/auth/token, below | No | Yes | Yes |
A team API key
A team key acts as the person who made it. It carries the rights picked when it was made, and the API caps them at the rights that person holds now, on every call: the key never carries more than its maker holds. A route's own right is not checked for a team key today (see Rights on each route). A key lives at most 90 days and can be revoked; a revoked key is refused on its next call.
curl 'https://openx.fathym.com/ox-api/warm-queries/<lookup>' \
-H 'Authorization: Bearer <YOUR_JWT_TOKEN>'
A person's token from an App Identity
- Trust the App Identity under Secure your workspace API, with the mode set to Hybrid or App Identity.
- Your app signs the person in through that directory's own sign-in app and asks for an access token with the scope the API Manager shows under Calling with a directory token. An ID token is refused; it must be an access token.
- Send it with the workspace header:
curl 'https://openx.fathym.com/ox-api/openapi' \
-H 'Authorization: Bearer <ACCESS_TOKEN_FROM_YOUR_DIRECTORY>' \
-H 'x-oi-workspace: <your workspace id>'
The API reads the person's rights from their access cards in this workspace, never from the token. The person
needs at least one card that grants a right, and every right the route needs. They are never treated as the
workspace owner. Only routes in the API catalogue are open to them; any other answers 403
OX_DOOR_ROUTE_NOT_SERVED.
You can add your own app, with its own client id, under API rights per app. Today a person's token asked for under any client other than the directory's own sign-in app is refused.
A job's own token
An automated job sends an app-only token from its own client in the directory. It is let in only while it is a live job of this workspace and its client id is not the directory's own sign-in client. Set jobs up in the App Identity window.
The job token swap
A job may trade its directory token for a short OpenX token, then send that instead:
curl -X POST 'https://openx.fathym.com/ox-api/auth/token' \
-H 'Authorization: Bearer <THE_JOB_DIRECTORY_TOKEN>' \
-H 'x-oi-workspace: <your workspace id>'
The answer is a standard OAuth token answer, sent with Cache-Control: no-store:
{ "access_token": "<OPENX_TOKEN>", "token_type": "Bearer", "expires_in": <seconds> }
- Its lifetime is the lifetime set on the job, else the workspace's Default job token lifetime (minutes), else what is left of the directory token, and never longer than what is left of the directory token.
- It names the job and carries no rights. Each call is decided on the job's access cards as they stand at that moment, so a revoke ends it on the next call.
- It cannot be swapped again, and it works only through
/ox-api. - Only a job's own directory token can be swapped; a team token cannot.
Rights on each route
A caller let in through an App Identity is checked against the rights each route needs; a missing one answers 403
OXAPI_REQUIRED_RIGHTS_MISSING with the MissingRights. For a team key, the API notes the rights a route needs
but does not yet refuse on them; the route's own checks still apply.
When a call is refused
Most refusals before the API knows who you are come back as the same plain 401, on purpose, so a caller cannot learn the workspace's mode or whether it exists:
{ "Message": "This request could not be authorized." }
The reason is written only to OpenX's own service log, which no window shows today. Work through a plain 401: check these in order. Every refusal, with what to do, is on API refusals.
Next steps
- What each refusal means -> API refusals
- The routes -> REST API
- Try a call in the browser -> API Manager