Secure your workspace API

Goal: Choose who can call your workspace API at /ox-api: your team, the people and jobs of an App Identity you trust, or both. Then decide what those App Identity callers may call.

Open APIs -> API Manager and press Manage. The Manage this API section opens. At its top is Access to your workspace API: "Choose who can call your workspace API at /ox-api: your team, the App Identities you trust, or both."

Who can change it

Only the workspace owner, or someone with the Workspace.API.Manage right, sees the Manage button. Everyone else does not see these settings at all. The server checks the same rule on every save. Workspace.Access.Manage alone no longer changes them.

Azi and agents cannot propose a change to the API access settings on this page. The automated jobs an agent may propose are accepted in the App Identity window, not here.

The three modes

The section shows the saved mode (Saved as:) and a Mode choice:

Mode	What the window says
Team	"Your team's OpenX sign-ins and API keys can call it. This is the default."
Hybrid	"Your team can call it, and so can people and jobs with an access token from an App Identity you trust."
App Identity	"Only people and jobs with an access token from an App Identity you trust can call it. Team sign-ins and team API keys are turned away."

A workspace that never chose a mode is in Team.

Hybrid and App Identity are left out of the choice, not greyed out, until one of your App Identities is ready: "Hybrid and App Identity appear here once one of your App Identities is ready for app calls. Open Environment, then App Identity, and use Configure for app calls." Open App Identity set-up takes you there. A workspace already saved in one of those modes keeps it listed, so you always see the mode you are in.

In Hybrid and App Identity the window also says: "With App Identity, the access cards you assign decide what each caller can reach. Every call from a directory token is checked against the cards of the person or job making it." That sentence is older than the access rules. What an App Identity caller can reach is now decided by the rules in Who may call, for App Identity callers. The caller's access cards still matter: they give the rights those rules are checked against.

What each mode admits

Caller	Team	Hybrid	App Identity
A team sign-in or team API key	Yes	Yes	No (401)
A person with a token from a trusted App Identity	No (401)	Yes	Yes
An automated job of a trusted App Identity	No (401)	Yes	Yes
A hosted workbench address, with a team key	Yes	Yes	No (401)
A hosted workbench address, with an App Identity token	No (401)	Yes	Yes

At a hosted workbench the API's own check turns those callers away first, with the same plain 401. The workbench's 403s (WORKBENCH_TEAM_MODE_OFF, WORKBENCH_APP_MODE_OFF) are a second check that a caller normally never sees.

Every refusal before the API knows the caller answers the same plain 401, so an outsider learns nothing about the workspace. What an admitted App Identity caller may then call is set in Who may call, for App Identity callers. How an app makes these calls is on Call the API from your app.

A team key's rights are not enforced route by route today. A call outside them is logged, not refused. The API Manager says the same in its key view: "An API key calling outside its rights is not yet refused, so treat the list as a guide."

Trusted App Identities

In Hybrid and App Identity, tick one or more Trusted App Identities: "Pick one or more App Identities that are ready for app calls." Tokens from any other directory are turned away. An App Identity that has stopped being ready is marked: "Not ready for app calls. Untick it, or run Configure for app calls again."

People can sign in through the directory's own sign-in app. To accept sign-ins through another app in the same directory, register it under Sign-in apps in the App Identity window, and Revoke it there to stop accepting them. Registering an app is trust only: "People signing in through one of them call as themselves, on their own access cards."

Default job token lifetime

Default job token lifetime (minutes) is optional: "Used for job tokens from OpenX's token swap when a job sets no lifetime of its own. Sign-in tokens keep the lifetime their directory gives them." Any whole number above zero; leave it blank for none. A swapped job token never outlives the directory token it was swapped for.

Save

Save access settings saves the mode, the trusted App Identities and the lifetime at once, and answers Saved. It saves only these settings, never the rest of the workspace, and it does not wait for Deploy. For an App Identity caller, the API reads the saved settings again on each call it lets in, so a revoke bites on the next call; a refusal may come from a copy up to 30 seconds old, so a caller you have just allowed can take that long to get in.

Message	When
Choose at least one App Identity to trust. Hybrid and App Identity modes need one or more.	Hybrid or App Identity with none ticked
The job token lifetime must be a whole number of minutes, above zero.	A lifetime that is not
The access settings were not saved. Check your connection, then try again.	The save never reached the server
The access settings were not saved (HTTP ...).	The server refused it without a reason of its own

A refusal from the server shows its own sentence; the save refusals are listed on API refusals.

Who may call, for App Identity callers

Once the saved mode is Hybrid or App Identity, Who may call, for App Identity callers shows below the access settings: "These rules decide what people and jobs signed in through a trusted App Identity may call. Rules stack: a call must pass the whole API, its tab and its endpoint, unless a level replaces the settings above it. Team sign-ins keep OpenX's own rights."

For these callers only these rules count. The rights an endpoint asks for in its own code are not checked.

Set the rules

Each level has the same row of controls:

• The whole API: Open or Closed.
• Each tab, and each endpoint inside it: Inherit, Open or Closed.
• When a level is Open, pick one or more of the workspace's access rights, and switch between All of these and Any of these. With no right picked, any account of the App Identity passes that level.
• At a tab or endpoint that is set, Replace the settings above makes that level stand alone instead of stacking on the levels above it.

Any Closed level that applies closes the endpoint. Under each tab and endpoint, a line starting Also applies says what the levels above add.

A caller's rights come from the access cards they hold in this workspace. A job's come from the access cards it was given in the App Identity window.

Save the access rules saves them and answers Access rules saved. It sends only what you changed.

One rule set, or one per App Identity

One rule set for all App Identities is the default. A rule set per App Identity gives each trusted App Identity its own copy of the shared set, picked with App Identity. An App Identity you trust later has no set yet: "Closed until you set its rules." Set its rules, starting from the shared set gives it one.

Use one shared set goes back to one set. Which set becomes the shared one chooses which set is kept.

Before any rules are saved

Until a manager saves rules, the whole API reads as Open with no right picked, and every tab and endpoint inherits it. The window says: "Only people with access in this workspace can call it until you set rules." In that state:

• A person signed in through a trusted App Identity reaches every endpoint if they hold at least one right in this workspace. A person with none gets the plain 401.
• An automated job the workspace admits reaches every endpoint.

Once rules are saved, even a saved Open with no right picked, a person with no access card can call an endpoint whose levels ask for no right.

While the whole API is Open with no right picked, the window warns: "The whole API is open with no rule: every endpoint with no setting of its own can be called by every account of the App Identity, the access routes included." The warning never blocks a save.

Split access by app

There is no split-access switch any more. A save that still carries one is accepted and the switch is dropped, and a switch stored from before is cleared on the next save.

The MCP server is apart

"The OpenX MCP server keeps its own team sign-in and is not affected by this setting." Open the OpenX MCP server takes you there. See MCP Server.

Next steps

• Call the API from your app -> Call the API from your app
• What each refusal means -> API refusals
• Prepare an App Identity -> App Identity