> For the complete documentation index, see [llms.txt](https://docs.ox.security/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ox.security/api-documentation/api-reference/ox-api-authentication.md).

# OX API Authentication

To start using OX API, you need to get a new API token. After that you can start sending requests.

OX API requests are subject to rate limits per API key.

| Limit type | Requests allowed        |
| ---------- | ----------------------- |
| Hourly     | 1,000 requests per hour |
| Daily      | 15,000 requests per day |

If a limit is reached, additional requests are blocked until the time window resets. For example, if you have fewer remaining daily requests than hourly requests, the daily limit becomes the active limit.

OX API responses include headers that indicate your current rate limit status.

| Header                | Description                                                                            |
| --------------------- | -------------------------------------------------------------------------------------- |
| `RateLimit-HourLimit` | Maximum number of requests allowed per hour.                                           |
| `RateLimit-DayLimit`  | Maximum number of requests allowed per day.                                            |
| `RateLimit-Limit`     | The active rate limit. This is the limit that will be reached first (hourly or daily). |
| `RateLimit-Remaining` | Number of remaining requests for the active limit.                                     |
| `RateLimit-Reset`     | Number of seconds until the active limit resets.                                       |

The active limit is determined by the most restrictive constraint at the time of the request.

### On-prem API URL

If your OX deployment is hosted on-prem, use your organization’s OX domain as the API base URL.

Use the following format:

`https://<CustomerDomain>/api/apollo-gateway`

Replace `<CustomerDomain>` with the domain of your on-prem OX environment.

The API path remains the same for both SaaS and on-prem deployments. Only the domain changes.

### API compatibility

To help avoid breaking existing integrations, OX does not introduce breaking changes to existing queries or mutations.

New APIs and fields may be added over time. Older APIs or fields may be marked as deprecated before they are retired.

If a breaking change is ever required, customers should be notified in advance.

## **Step 1: Create a new API token \[OX]**

Create an API key to authenticate requests to the OX API. Each API key has its own permissions, similar to an OX user account. When you create a key, you assign it a **role** that determines what actions it can perform and a **scope** that determines which applications it can access.

1. In OX, go to **Settings** > **Organization** > **API Keys**.
2. Click **Create API Key**.

<figure><img src="/files/8wsjoQCxsOAK7MAy8wNZ" alt="" width="512"><figcaption></figcaption></figure>

3. Configure the following settings:

<table><thead><tr><th width="220.666748046875">Setting</th><th>Description</th></tr></thead><tbody><tr><td><strong>API Key Name</strong></td><td>Enter a descriptive name for the API key.</td></tr><tr><td><strong>API Key Type</strong></td><td>Select the purpose of the API key:<br><br>- <strong>CI/CD Integration</strong>: Authenticate CI/CD pipeline integrations.<br>- <strong>API Integration</strong>: Authenticate applications that access the OX API.<br>- <strong>IDE/CLI Integration</strong>: Authenticate IDE extensions or CLI tools.<br>- <strong>K8s Inspector/Runtime Sensor Integration</strong>: Authenticate Kubernetes Inspector and Runtime Sensor integrations.<br>- <strong>VibeSec/MCP Integration</strong>: Authenticate VibeSec and MCP integrations.</td></tr><tr><td><strong>Assign role</strong></td><td>Select the role that defines what the API key is allowed to do in OX. API key roles use the same permission model as OX user roles. For information about available roles and their permissions, see the <strong>Roles</strong> documentation.</td></tr><tr><td><strong>Assign scope</strong></td><td>Select which applications the API key can access:<br><br><strong>Entire organization</strong>: Grants access to all applications in the organization.<br><strong>Custom</strong>: Limits access to applications that match the selected <strong>App Owners</strong> and <strong>Tags</strong>.</td></tr><tr><td><strong>Expiration Date</strong></td><td>Select when the API key expires. After this date, the key can no longer be used to authenticate API requests.</td></tr></tbody></table>

4. Click **Create**.
5. Copy the generated API key and store it securely. You won't be able to view it again after closing the dialog.

> **Important:**\
> Treat API keys like passwords. Store them securely and never commit them to source control or include them in application code.

#### Understanding roles and scopes

An API key uses the same authorization model as an OX user:

* The [role](/admin-settings/roles.md) determines what actions the API key can perform.
* The [scope](/admin-settings/scopes.md) determines which applications the API key can access.

For example, you can create an API key with a Viewer role that has access to the entire organization, or an Admin role that is limited to applications with specific App Owners or Tags.

This allows you to grant integrations only the permissions and application access they require.

## Step 2: Send an authenticated request \[Postman]

1. In the **Postman**, add the collection and then:

* Select request method `Post`.
* Use the API URL:
  * SaaS: `https://api.cloud.ox.security/api/apollo-gateway`
  * On-prem: `https://<CustomerDomain>/api/apollo-gateway`
* In **Headers** > **Authorization**, add the OX API key.

<figure><img src="/files/fIqT8r0fTfQEgvc4BR9H" alt=""><figcaption></figcaption></figure>

2. In the **Body** section, add query and click **Send**.

<figure><img src="/files/0pVAeEQ30YM8b2MG96x3" alt=""><figcaption></figcaption></figure>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.ox.security/api-documentation/api-reference/ox-api-authentication.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.