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, set tenant-wide rate limits, and issue named credentials that authenticate every request with full audit context.
The Programmable Access page combines interface toggles, tenant-wide rate limits, a credentials table, and a usage overview in a single workspace.
Key Concepts
Before issuing credentials, understand the three layers that govern programmable traffic. They are enforced on every request in the order listed:
| Layer | Scope | What it controls |
|---|---|---|
| Interface toggles | Tenant | Which programmable interfaces are available at all (Runtime API, CLI, MCP) |
| Tenant rate limits | Tenant | Default request ceiling applied when a credential does not override it |
| Credentials | Per credential | Identity, scoping, per-credential overrides, and lifecycle state |
Every request to a programmable interface must present a credential. The credential determines the caller identity, what group access its queries are evaluated against, and which rate limit applies.
Interfaces
The Interfaces panel toggles each programmable surface on or off for the entire tenant. Disabling an interface immediately rejects new requests on that surface — existing sessions are not affected, but no new traffic will be accepted.
| Interface | Protocol | Typical caller |
|---|---|---|
| Runtime API | REST over HTTPS | Backend services, internal applications, server-side jobs |
| CLI | REST over HTTPS (via askrai command) | Power users, operators, scripts in terminals |
| MCP | Model Context Protocol over HTTP | AI agents (Claude, Copilot, Cursor, custom agents) |
Leaving an interface disabled is the fastest way to prevent programmatic access entirely. Treat interface toggles as the tenant-wide kill switch for programmable access — credential-level controls sit inside this boundary.
Tenant Rate Limits
The Rate Limits panel sets the default request ceiling applied to every credential that does not define its own override. Three knobs are exposed:
| Field | Description | Default |
|---|---|---|
| Requests per minute | Peak throughput per tenant | 300 |
| Requests per day | Rolling 24-hour request ceiling | 50,000 |
| Max concurrent streams | Maximum simultaneous streaming connections | 50 |
Type new values and click Save to apply them. The Save button is disabled until you have made a change. Updates take effect for all requests made after the save completes.
Tenant rate limits are a floor, not a hard quota. Individual credentials can opt in to stricter per-credential rate limits (see below) — but no credential can exceed the tenant values unless you raise them here first.
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 authenticates against (API, CLI, or MCP) |
| Status | Active, Revoked, or Expired (shown as an additional pill) |
| 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, orRevoked
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, audited, and (in future releases) rotated.
| Type | Intended holder | Typical lifetime | Notes |
|---|---|---|---|
| Personal Token | A named human, tied to their identity | Short (days to weeks) | Automatically revoked when the user is offboarded |
| 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) | Enables agent_augmentation execution mode and agent-specific audit tagging |
| Scoped API Key | A narrowly-scoped integration | Varies | Used when you need per-caller rate limits and IP allowlists |
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 valid on — API, CLI, or MCP. Requests on other interfaces are rejected with 403 |
| Group | Optional. When set, queries made with this credential inherit the group's knowledge pack and guardrail assignments. Personal Tokens inherit from the user's groups instead |
| Caller Type | Human, Application, or Agent. Drives role mapping rules that use the Caller Type or Credential Type rule operators |
| 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 |
Execution modes let you build safer agent pipelines. A credential limited to Agent Augmentation will receive structured context rather than a rendered answer, and will be audited with an agent_augmentation execution tag.
Add Security Boundaries
Two optional fields further constrain the credential:
| Field | Description |
|---|---|
| IP Allowlist | Comma-separated list of IPv4 addresses or CIDR ranges. Requests from other addresses are rejected before authentication. Leave empty to allow any source |
| Expires At | Optional absolute expiration. After this timestamp the credential is treated as expired and rejects new requests. Leave empty for a non-expiring credential |
(Optional) Override Rate Limits
Expand Per-credential rate limit overrides to apply tighter limits than the tenant defaults:
| Field | Default |
|---|---|
| Requests per minute | 60 |
| Requests per day | 10,000 |
| Max concurrent streams | 5 |
| Max prompt characters | 10,000 |
These four values replace the tenant defaults only for this credential and cannot exceed them. The max_prompt_chars override is a per-credential safety limit on the size of prompts accepted from this caller.
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 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 details drawer groups metadata into General, Security, and Lifecycle sections with lifecycle actions at the bottom.
| Section | Fields |
|---|---|
| General | Description, Channel, Caller Type, Execution Modes |
| Security | IP Allowlist, per-credential rate limit overrides (RPM, Daily Limit, Max Concurrent, Max Prompt Chars). If no overrides are set, the drawer displays Using tenant defaults |
| 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 | Marks the credential Revoked. Future requests are rejected immediately. The credential remains in the table for audit purposes |
| Rotate Key | Status is Active | Generates a new secret for the same credential ID and shows it in the secret modal. The old secret stops working immediately. Usage counts, groups, and rate limits are preserved |
| Delete | Always | Removes the credential permanently. Use Revoke instead if you want to keep an audit trail |
Rotating an active credential invalidates the previous secret immediately. Schedule rotations for windows where callers can pick up the new secret, or rotate credential pairs if you need zero-downtime handover.
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 any further API calls using the secret return 401 Unauthorized.
Usage Overview
The Usage Overview panel at the bottom of the page summarises programmable traffic at a glance. It reads directly from the credential list and updates automatically as you filter or paginate:
| Metric | What it shows |
|---|---|
| Total Requests | Sum of Usage Count across all displayed credentials |
| Active Credentials | Count of credentials currently in Active status |
| Enabled Interfaces | How many of the three interfaces (API, CLI, MCP) are turned on, out of three |
Two charts follow the metric cards:
- Requests by Interface — bar chart grouping total requests by channel, useful for spotting interface-level surges
- Top Credentials by Usage — the five busiest credentials ranked by
Usage Count. A quick way to find noisy callers that may deserve their own rate limit override
The Usage Overview is scoped to whatever filters you have applied to the credentials table. Clear filters to see a tenant-wide view, or narrow to a single type to spot which credential class is driving load.
How Programmable Access Fits the Platform
Programmable Access sits alongside the traditional human channels (Teams, Web Chat, Email, Phone) 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 credential's Caller Type, Channel, and Group are propagated into
RequestContextand surface in the Conversation Logs, Dashboard, and Sandbox panels. - Execution modes let you opt into agent-friendly response shapes.
agent_augmentationmode returns structured context and suggested next actions instead of a rendered answer, so downstream agents can compose their own response.
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, Device, or Location — giving you the same declarative access model for machine traffic that you use for human traffic.
Related Pages
- 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