Programmable Access
Issue and govern API, CLI, MCP and A2A credentials that let external applications and AI agents query AskRAI, or hand work to a project's agent, with enterprise-grade controls
Programmable Access turns AskRAI into a governed data plane for your external applications, CLI workflows, and AI agents. From this page you decide which machine-to-machine interfaces are enabled for your tenant, cap how many queries the tenant sends each minute and each day and how many it runs at once, and issue named credentials that authenticate every request with full audit context.

The interface toggles are the outer gate, and they fail closed: turning one off refuses every credential carrying that Channel, however the credential itself is configured.
Programmable Access opens to the holders of View credentials and Manage credentials. View reads every credential's settings, limits and usage, and which interfaces are on, read-only: it never shows a secret, and offers no rotate, revoke or delete. Manage creates, rotates and revokes credentials and turns the interfaces on and off. A Member does not see Programmable Access in the Admin sidebar — they cannot open the Admin plane at all — and a Member who follows a direct link to it is sent back to the Projects workspace. Roles are assigned under Admin → Access.
Key concepts
Before issuing credentials, understand the three layers that govern programmable traffic:
| Layer | Scope | What it controls |
|---|---|---|
| Interface toggles | Tenant | Which credentials are accepted, by the Channel each was created with (API, CLI, MCP, A2A) |
| Rate limits | Tenant and per credential | How many queries may be sent each minute and each day, and how many may run at once. A credential also caps how long a prompt may be |
| Credentials | Per credential | Identity, scoping, IP allowlist, expiry, and lifecycle state |
Every request to a programmable interface must present a credential. The credential determines the caller identity and what group access its queries are evaluated against.
Interfaces
The Interfaces panel turns each programmable interface on or off for the entire tenant. Each toggle governs the credentials created with its Channel, wherever they are used: turning one off refuses every later request those credentials send, in a conversation or an MCP session already open too, while a query already admitted runs to its end. The public API refuses them from the next request. Through the MCP server, a tool call fails from the next call, and connecting or listing tools within a minute.
| Interface | Protocol | Typical caller | Accepts |
|---|---|---|---|
| Runtime API | REST over HTTPS | Backend services, internal applications, server-side jobs | A credential of any Channel but A2A, while that Channel's interface is on |
| CLI | REST over HTTPS (via askrai command) | Power users, operators, scripts in terminals | A credential of any Channel but A2A, while that Channel's interface is on |
| MCP | Model Context Protocol over HTTP | AI agents (Claude, Copilot, Cursor, custom agents) | Only a credential with Channel MCP, while MCP is on |
| A2A | A2A 1.0 over JSON-RPC (HTTPS) | Agents outside AskRAI handing work to a project's agent | A credential with Channel A2A or API that the agent lists under External access, while that Channel's interface is on |
The askrai CLI is not generally available yet, and there is nowhere to install it from. Its interface and its Channel are on this page already, and what the page says of the CLI describes how it behaves. Until it is available, call the public API directly, or connect an AI agent to the MCP server.
The CLI calls the public API as any other caller does and sends nothing that names it, so AskRAI cannot tell it from the Runtime API. Turning CLI off refuses the credentials created with Channel CLI, from the CLI and from any other caller alike. It does not stop the CLI, which goes on working with a credential created with Channel API while Runtime API is on, or with Channel MCP while MCP is on.
Turning all four interfaces off refuses every credential the tenant holds: together the toggles are the tenant-wide kill switch for programmable access, and credential-level controls sit inside this boundary. To stop one caller, revoke its credentials instead.
Certificates the CLI trusts
The askrai command verifies AskRAI's certificate against the trust store of the operating system it runs on: the keychain on macOS, the certificate store on Windows, and the system CA certificates on Linux. It carries no certificate bundle of its own.
- A root certificate your organization installed in that store is trusted, so the CLI works behind a proxy that inspects TLS once the proxy's root is installed there.
- A certificate authority the operating system does not list is not trusted, including one found only in a bundle that a Python package such as
certifiships.
When the CLI refuses a certificate it reports API error: Cannot connect to API, the same message it gives for a host it cannot reach.
Terms the CLI is provided under
The askrai command is governed by the AskRAI customer agreement, and askrai --help says so. The open-source packages installed with it are each provided under their own license: the CLI's package carries their license texts in THIRD_PARTY_NOTICES.txt, beside its own LICENSE.
Tenant rate limits
The Rate Limits panel holds the tenant-wide limits on programmable traffic. Every credential the tenant holds counts toward them together:
| Limit | What it caps | Default |
|---|---|---|
| Requests per minute | Queries the tenant's credentials may send in each minute | 300 |
| Requests per day | Queries the tenant's credentials may send in each day | 50,000 |
| Max concurrent streams | Queries the tenant's credentials may have in flight at once | 50 |
Type new values and click Save to apply them. The Save button is disabled until you have made a change. A new value normally applies within a few seconds of the save, and always within five minutes.
Each value must be a whole number of at least 1. Any other value is refused under its box, and Save stays disabled until it is corrected; the server refuses the same values too. A limit of 0 would reject every query of every credential the tenant holds, so it is not how programmable access is turned off: use the interface toggles above.
Requests per minute can be at most Requests per day, since a per-minute limit above the day's could never be reached. A higher one is refused under its box, and Save stays disabled until one of the two is changed. Limits saved before this check stay in force as saved until you save new ones.
Every limit applies, and none is unlimited. A request budget or prompt length saved before those limits were enforced applies as it was saved. A credential created with only a Max concurrent streams override holds the defaults for its other three limits, and those apply. A tenant or credential with no value of its own for a limit takes that limit's default.
How limits are checked
Each request budget and concurrency limit is checked at two independent levels, and both must have headroom: the credential's own limit — its override, or the default — and the tenant's. The tenant's limits are a hard cap, not a floor: a credential never sends more queries in a minute or a day, or runs more at once, than the tenant allows, whatever its own limits say, so its effective limit is the smaller of the two.
- Queries and A2A handoffs count:
POST /v1/queryandPOST /v1/query/stream, whether the API, the CLI or MCP sent them, and an outside agent'sSendMessageto a project's agent over A2A. Other calls, such as reading sessions or audit records, an A2AGetTaskorCancelTask, or reading an agent's card, are neither counted nor refused by a budget. - A query counts once, when it is admitted — after its key, its prompt length, its execution mode, every request budget and both concurrency limits have accepted it. A streamed query counts once, as its stream starts, not per part of the answer. A
SendMessagecounts once its key, its address and its message pass their checks, one its agent then rejects included, and a repeat of one already answered, with the samemessageId, is not counted again. It takes no concurrency slot, as it is answered at once. - A refused query counts against nothing. Whichever of those checks refuses it, no budget is spent, so a credential that spends its own budget does not go on spending its tenant's. An admitted query stays counted whatever its answer, a blocked or failed one included.
- Request budgets are counted in fixed UTC windows: a per-minute budget in each whole minute of UTC, a per-day budget in each UTC day, starting at 00:00 UTC. The count does not slide, so a caller that spends its per-minute budget at the end of one minute can spend it again at the start of the next: up to twice the per-minute budget can arrive within 60 seconds.
- Concurrency bounds how many queries run at once, not how many arrive over time. A query counts as a stream from the moment it is admitted until its answer is complete, whether or not the caller asked for a streamed response.
What a caller sees when refused
A query refused by a spent request budget is answered 429 with the code RATE_LIMITED and a Retry-After header holding the whole seconds until the window that refused it renews. Its detail says whose budget was spent, how large it is and when it renews, for example:
This credential's budget of 60 requests per minute is spent. It renews in 23 seconds.
The tenant's budget of 50000 requests per day is spent. It renews at 00:00 UTC, in 3600 seconds.On POST /v1/query/stream the refusal arrives before the stream starts, as the same 429, and an A2A SendMessage is refused with the same 429 too. The CLI and the MCP tools show the detail as it is written. A query refused because a concurrency limit is full is answered 429 with the code RATE_LIMITED too.
A credential whose budget is 0 is answered the same 429 with no Retry-After, because no window renews it, and a detail such as This credential's budget of 0 requests per minute refuses every query.
A prompt longer than the credential's Max prompt characters is answered 400 with the code INVALID_REQUEST and a detail such as The prompt is 812 characters, over this credential's limit of 500. A prompt longer than 10,000 characters, the platform's ceiling, is refused whatever the credential allows, with 422. Neither counts against any budget.
A caller whose keys keep being refused is held back, separately from these limits. Once around ten keys from one address have been refused within a minute, every key sent from that address is rejected with 429 and a Retry-After header until the minute is up, a working one included. The limit is the platform's and cannot be changed per tenant. An integration whose key was rotated or revoked should move to its new key rather than retry the old one. AI agents that connect through the hosted MCP server are counted by their own address, not by the server's. Agents that share an address are not all stopped by one of them: the server verifies a working key again once a minute, and until a key is next due it goes on being accepted while its address is held back. A key that comes due in that time, or one the server has not yet verified, waits until the address is released.
Credentials
The Credentials table lists every credential issued for this tenant, regardless of status. Each row summarises identity, interface, lifecycle, and usage in a compact form:
| Column | Description |
|---|---|
| Name | Human-friendly identifier chosen when the credential was created |
| Type | One of Personal Token, Service Account, Agent Credential, or Scoped API Key |
| Channel | Interface this credential was created for (API, CLI, MCP, or A2A), whose toggle it depends on |
| Status | Active, Interface off (its Channel's interface is turned off, so it cannot sign in until that interface is on), Expired (past its expiry, so it can no longer sign in), or Revoked |
| Last Used | Relative timestamp of the most recent successful authentication |
| Usage | Running counter of successful requests |
| Created | Creation date |
| Actions | Row-level menu with Revoke, Rotate, and Delete |
Filtering credentials
The filter bar above the table narrows the list by name, type, or status:
- Search — free-text match against the credential name
- Type —
All,Personal Token,Service Account,Agent Credential, orScoped API Key - Status —
All,Active,Interface off,Expired, orRevoked.Activeleaves out a credential past its expiry or whose interface is off
Filters are applied on the server and combined with AND semantics — only credentials matching every selected filter are returned.
Credential types
Choose the type that best reflects who or what will hold the secret. The type drives how the credential is displayed and how its traffic is attributed in the audit trail and on the dashboard.
| Type | Intended holder | Typical lifetime | Notes |
|---|---|---|---|
| Personal Token | A named human, tied to their identity | Short (days to weeks) | Revoke it by hand when the user is offboarded — see the warning below |
| Service Account | An unattended backend service | Medium (months) | The most common choice for server-side integrations |
| Agent Credential | An AI agent acting on behalf of a user | Medium (months) | Carries an agent-specific audit tag. It does not by itself enable agent_augmentation — execution modes are set separately and are available to every type |
| Scoped API Key | A narrowly-scoped integration | Varies | Used when you want an IP allowlist and tight rate limits |
The credential type is a label, not a control. It changes how the credential is displayed and audited — it does not change what the credential is allowed to do. In particular, deleting or deprovisioning a user does not revoke their Personal Tokens: nothing in the offboarding or directory-sync path touches credentials. When someone leaves, revoke their credentials on this page by hand.
Creating a credential
Open the Create Credential Dialog
Click Create Credential in the top-right of the page. A modal opens with the full credential form.

The Create Credential dialog collects identity, scoping, and per-credential override settings in a single form.
Enter Identity Fields
Fill in the required identity fields:
| Field | Required | Description |
|---|---|---|
| Name | Yes | Alphanumeric identifier (max 128 chars). Must start with a letter or digit and may contain hyphens and underscores. Used in logs and the credentials table |
| Description | No | Free-text explanation of what the credential is for (max 500 chars). Appears in the details drawer |
| Credential Type | Yes | One of the four types described above |
Scope the Credential
Choose which interface and audience this credential belongs to:
| Field | Description |
|---|---|
| Channel | Which programmable interface the credential is for — API, CLI, MCP, or A2A. The credential works only while that interface is on, and its queries are recorded under that Channel. While it is off, the dialog says so under Channel, with a Go to Interfaces link to its switch, and the credential is still created. The MCP server admits only a credential with Channel MCP; the Runtime API and the CLI admit any Channel but A2A (see below). An A2A credential cannot be a Personal Token |
| Kind | With Channel A2A only: an API key, an OAuth client, whose Client ID and Client secret an outside agent exchanges for short-lived tokens, or a Signing key, the Public key of a key an outside agent signs its own tokens with, and the Issuer and Audience those tokens carry. Which kind an agent takes is its External access method. A signing key holds no secret, so it is never rotated: register its replacement instead |
| Group | Optional. When set, the credential is added as a member of that group, so its queries are evaluated against the group's knowledge pack and guardrail assignments. The credential works only while that group governs it (see below), so only active groups are listed. With None, the credential belongs to no group and no group's knowledge packs or guardrails apply to it. Personal Tokens inherit from the user's groups instead |
| Caller Type | Human, Application, or Agent. Drives role mapping rules of the Caller Type rule type — a rule's type is what it reads, its operator is how it compares (equals, contains, in, not_in, between) |
| Execution Modes | Select one or both of Interactive User (a human is in the loop) and Agent Augmentation (an agent synthesises the response). Leaving this empty allows either mode |
Only the MCP server holds a credential to its Channel. An AI agent connecting through the MCP server needs a credential created with Channel MCP, and one created with Channel API is refused with This key is for the API channel; create a key with Channel MCP. (a CLI one is told the same, naming CLI). The CLI sends nothing that tells it from the Runtime API, so a request from either is checked against the interface of the credential's own Channel: a credential created with Channel API works from the CLI while Runtime API is on. When the credential's interface is off, the request fails with 401 and the code UNAUTHORIZED, not 403, and its detail names the interface, such as The API interface is turned off for this organization. The CLI and the MCP server show the same reason.
An A2A credential calls only the agents that list it, over A2A. It is the credential an agent outside AskRAI holds, made from an agent's External access tab with Create key, or here with Channel A2A. Any other request it sends, a query, a session or audit read, or the CLI's sign-in check, is refused with 403, the code CHANNEL_DENIED and An A2A key calls only the A2A endpoint of an agent that lists it. An agent connecting through the MCP server with one is refused with 401 instead, with the same reason, and the Sandbox does not offer it to test as. An agent may also list a credential with Channel API, which goes on answering queries too: every credential made before A2A credentials existed keeps the Channel it was made with, so an agent that already lists one keeps answering it. A2A is off until it is turned on here, as every interface is, and while it is off the External access tab marks each A2A credential it lists Interface off.
A credential with a group works only while that group governs it. Every request checks that the group still exists, is active and still lists the credential. If it does not, the request is rejected with 403 and the code CREDENTIAL_UNGOVERNED, and nothing is revoked. An agent connecting through the MCP server is refused with 401 instead, with the same reason. The credential works again as soon as the group is reactivated or its membership is restored, and rotating the key puts the credential back in its group if the group still exists. The console keeps the membership in place: a group cannot be deleted while it governs an active credential, and a credential is removed from its group only by revoking or deleting it.
A credential is not created in an inactive group. Pick a group that was deactivated while the dialog was open, and Create is refused with The group this key was to join is inactive, and a key in an inactive group cannot sign in, so the key was not created. The dialog keeps your entries and marks the group This group is inactive. Choose another group. Rotating a credential whose group has gone inactive is still allowed, and the new secret signs in once the group is active again.
When a credential has execution modes set and a request does not name one, the least-augmenting mode the credential allows is applied — Interactive User whenever it is one of them, whatever order you ticked the boxes in. A request that names a mode outside the credential's list is rejected with 403.
Agent Augmentation is additive, not a replacement. A caller in agent mode still receives the rendered answer; it simply arrives alongside an extra agent_context block (suggested next action, blocked reason, whether the answer was knowledge-grounded, and the source type). The mode also reshapes the summarisation prompt. It never suppresses the answer, so do not use it to withhold prose from a downstream agent.
Add Security Boundaries
Two optional fields further constrain the credential:
| Field | Description |
|---|---|
| IP Allowlist | Comma-separated list of IPv4 addresses or CIDR ranges. An entry that is neither is marked on the field, and no credential is created. Requests from other addresses are rejected with 403. Leave empty to allow any source. Through the MCP server, the address checked is the one that server reaches AskRAI from, not the agent's, so an allowlist of the agent's addresses refuses it, with 401 and This key's IP allowlist does not include the address the MCP server reaches AskRAI from. rather than 403 |
| Expires At | Optional absolute expiration, which must be in the future: a time already past is refused on the field and no credential is created. After this timestamp the credential is treated as expired and rejects new requests with 403 and Credential has expired, or with 401 and the same reason for an agent connecting through the MCP server. Leave empty for a non-expiring credential |
The allowlist is evaluated after the API key itself is verified, not before it — it narrows where a valid key may be used, and is not a pre-authentication network filter.
(Optional) Override the Rate Limits
Expand Per-credential rate limit overrides to set this credential's own limits. A box left blank gives the credential that limit's default:
| Field | What it caps | Default | Allowed values |
|---|---|---|---|
| Requests per minute | Queries this credential may send in each minute | 60 | A whole number, 0 or more |
| Requests per day | Queries this credential may send in each day | 10,000 | A whole number, 0 or more |
| Max concurrent streams | Queries this credential may have in flight at once | 5 | A whole number, 0 or more |
| Max prompt characters | The longest prompt this credential may send | 10,000 | A whole number from 1 to 10,000 |
A value of 0 in any of the first three rejects every query the credential sends. A value outside these bounds is refused, by the dialog and by the server. Requests per minute can be at most Requests per day, a blank box counting as its default, so a credential blocked with 0 requests per day needs 0 requests per minute too. 10,000 characters is the platform's ceiling for a prompt, and no credential can raise it.
You can change a credential's limits later from its details drawer, without moving the integration to a new key: see Changing a credential's limits. Rotating its key keeps them.
The request budgets and the concurrency limit are not validated against the tenant's when you save — a credential can be saved with a number larger than its tenant's, and nothing clamps it. The larger number buys nothing: the tenant's limit and the credential's are both checked on every query, and the stricter one wins.
Create and Copy the Secret
Click Create. The server generates the API key and returns it exactly once in a modal:
The API key is shown only at creation time. Copy it to a secret manager immediately — there is no way to retrieve it again. If the secret is lost, rotate the credential to issue a new one.
Use the copy button, paste the key into your secret store, check I have copied this API key, and click Done to dismiss the modal. The new credential appears in the table with Active status, or Interface off while its Channel's interface is off, and a usage count of zero.
Viewing credential details
Click any credential row to open the details drawer on the right. The drawer is organised into three sections that mirror the create form:

The secret itself is never shown again after creation. Rotate Key issues a new one, which works at once, and invalidates the old one within a few seconds (always within five minutes), keeping the credential's ID, groups, rate limits and usage history.
| Section | Fields |
|---|---|
| General | Description, Channel, Caller Type, Execution Modes |
| Security | IP Allowlist |
| Rate Limits | Requests Per Minute, Requests Per Day, Max Concurrent Streams and Max Prompt Characters, each as it applies, marked (default) when the credential has no value of its own (for example 60 (default)). Whatever they say, the credential is held inside the tenant's limits too. Edit Limits changes them for a credential that is not revoked |
| Lifecycle | Created timestamp, Created By, Expires At, Last Used (relative), Last Rotated, Usage Count |
The footer exposes three lifecycle actions. Which actions are available depends on the current status of the credential:
| Action | Available when | Effect |
|---|---|---|
| Revoke | Status is Active, Interface off or Expired | Marks the credential Revoked. Requests using it are rejected within a few seconds, and always within five minutes. The credential remains in the table for audit purposes |
| Rotate Key | Status is Active or Interface off | Generates a new secret for the same credential ID and shows it in the secret modal. The new secret works at once, and the old one stops working within a few seconds, and always within five minutes. Usage counts, groups, and the rate limits are preserved |
| Delete | Always | Removes the credential permanently. Requests using it are rejected within a few seconds, and always within five minutes. Use Revoke instead if you want to keep an audit trail |
Rotating an active credential invalidates the previous secret within a few seconds, so callers still holding it start failing almost at once. Schedule rotations for windows where callers can pick up the new secret, or rotate credential pairs if you need zero-downtime handover.
Revoking, rotating or deleting takes effect on every server of the public API within a few seconds, and always within five minutes. Five minutes is the longest a server keeps a credential it has already checked, if the notice of the change does not reach it. A query admitted before then also runs to its end. Treat a leaked secret as usable for that long after you revoke it.
Changing a credential's limits
An integration that needs a larger budget, or one you want to hold back, keeps its key: you change the limits of the credential it already uses.
Open the Edit
Click the credential's row to open its details drawer, then click Edit Limits beside Rate Limits. The edit is offered for any credential that is not revoked.
Type the New Limits
The four boxes open on the limits the credential holds now, or blank when it holds none of its own. They take the same values as when the credential is created, and a box left blank gives the credential that limit's default, which its placeholder shows. A value outside the allowed range is refused under its box, and Save stays disabled until it is corrected.

Each box opens on the limit as it applies now; the tenant's limits still hold the credential whatever you save.
Save
Click Save. The drawer shows the new limits, and they apply to the credential's next query within a few seconds, and always within five minutes. Cancel leaves the limits as they were.
What the credential has already sent in the current minute and day still counts. A credential refused at a budget of 2 requests per minute that you raise to 3 is admitted again within the same minute, for one more query; a budget you lower below what it has already sent refuses its queries until the window renews.
Only the rate limits can be changed. A credential's name, description, group, IP allowlist and expiry stay as they were set when it was created.
Revoking a credential
Open the Details Drawer
Click the credential row or choose Revoke from the actions menu (⋮) on the row.
Confirm the Revocation
A confirmation dialog asks you to confirm. Revoking is a soft-delete: the credential stays visible in the table with Revoked status so auditors can still see who issued it and when, but API calls using the secret return 401 Unauthorized within a few seconds, and always within five minutes.
Usage Overview
The Usage Overview panel at the bottom of the page summarises programmable traffic at a glance. Its figures cover every credential your tenant holds, whatever the credentials table above it is filtered to or paged to:
| Metric | What it shows |
|---|---|
| Total Requests | Sum of Usage Count across every credential, revoked ones included |
| Active Credentials | Count of credentials in Active status, so neither expired nor revoked, and on an interface that is on |
| Enabled Interfaces | How many of the four interfaces (API, CLI, MCP, A2A) are turned on, out of four |
Below the metric cards:
- Requests by Interface — bar chart grouping total requests by channel, useful for spotting interface-level surges
- Top Credentials by Usage — a two-column table (Name, Requests) ranking the five busiest credentials, of any status. A quick way to find noisy callers
Filtering or paging the credentials table does not change the Usage Overview. The figures are read when the page opens and again after you create, revoke or delete a credential; reload the page to see requests made since. To compare one credential type's load, filter the table by type and read each credential's Usage Count.
How Programmable Access fits the platform
Programmable Access sits alongside the human channel — Teams, the only one delivering traffic today — in the runtime pipeline. A request from a programmable credential is handled the same way as a human request — it is evaluated by guardrails, routed through auto-route or routing rules, and audited into the same conversation log — with two key differences:
- Identity comes from the credential, not from an end-user SSO session. The caller type, channel, caller name, credential ID and credential type travel with the request and surface in the Conversation Logs, Dashboard, and Sandbox panels. The group is not sent with the request — instead, the credential is enrolled as a member of the group when you create it, so group-scoped knowledge and guardrails resolve from that membership. A credential whose group no longer governs it is refused rather than answered without the group's controls.
- Execution modes let you opt into agent-friendly response shapes.
agent_augmentationadds a structuredagent_contextblock (suggested next action, blocked reason, grounding, source type) alongside the rendered answer.
Credentials also participate in the role system. When you create a role under Users, Roles & Groups, you can match on Caller Type or Credential Type in addition to Channel and Authentication — giving you the same declarative access model for machine traffic that you use for human traffic.
Related pages
- Connect an AI agent (MCP) — the MCP server's address, an example client configuration, and the tools it offers
- External Access (A2A) — open a project's agent to agents outside AskRAI, which call it with a key issued here
- Users, Roles & Groups — define Caller Type and Credential Type rules that map programmable traffic to roles
- Sandbox — test credential behaviour, including group resolution and execution modes, before pointing live traffic at the credential
- Dashboard — monitor programmable traffic volume and top callers across your tenant
- Conversation Logs — filter by API, CLI, or MCP channel and by caller type to investigate specific credential activity
- Model Routing — set tenant-level fallback models for the pipeline stages exercised by programmable traffic