API Access
AI CTRL's gateway is OpenAI-compatible, so tools built for the OpenAI API can be pointed at your AI CTRL environment instead of a third-party service. Access is controlled by your administrators and is off by default.
API usage is billed separately. Front-end chat falls under fair use. Anything running through the API is metered against your organization's consumption, and a script has no natural pace limit the way a person typing does. Treat enabling API access as a consumption decision as much as a security one.
For endpoint reference and request formats, see the Expedient API documentation.
Enabling access
| Setting | Controls |
|---|---|
| Global API setting | Whether API keys can exist in your deployment at all |
| Group permission | Whether a specific group can create keys |
The global setting sits above group permissions. If it's off, granting a group the API key permission does nothing, with no error explaining why. This is the most common reason an admin grants access and the user still can't generate a key. Turn it on first.
Turn on the global setting
- Go to Admin Panel → Settings → Authentication
- Find Enable API Keys
- Toggle it to green
- Click Save
Grant access to a group
Rather than opening access to everyone, grant it to a named group:
- Leave API keys off in your default user permissions
- Create a group, for example API Users
- Grant that group the API key permission
- Add the people who need it
That keeps the blast radius small and gives you one place to look when you want to know who has programmatic access. Permissions stack: a user in several groups gets the highest permission any one of them grants.
Generating a key
Once access is granted, each user creates their own:
- Click your profile picture, then Settings
- Open the Account tab
- Click Show next to API keys
- Click Create new secret key
- Copy the key and store it securely
The key is shown once. It authenticates as that user and carries that user's model access, so wherever the key ends up, so does that access.
Most tools store API keys in plain text: config files, environment variables, scripts. Never commit a key to a repository or share it between people.
Connecting a tool
| Setting | Value |
|---|---|
| Base URL | Your gateway address with /api/v1 appended, e.g. https://chat.yourcompany.com/api/v1 |
| API key | The key generated above |
| Model | The exact model identifier, not its display name |
Model identifiers are in Admin Panel → Settings → Models, beneath each model's display name.
For a worked example, see Configuring OpenCode with AI CTRL for VS Code.
Scope of API access
Interface features don't come with it. A tool using the API gets models and completions. Knowledge collections, the structured data tool, and prompt templates are built into the AI CTRL interface and stay there.
Model access follows the user. If a premium model is restricted to a privileged group, a key created by someone outside that group can't reach it either. Usually what you want, but worth knowing before someone reports a model as broken.