> 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:///api/apollo-gateway` Replace `` 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**.
3. Configure the following settings: | Setting | Description | | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | API Key Name | Enter a descriptive name for the API key. | | Key Ownership |

Select the ownership type:

- Personal (User-Bound): The API key inherits the role and scope of the user who creates it. Changes to the user's role or scope automatically affect the API key's permissions.
- Organization (Static Role): The API key has its own assigned role and scope, independent of the user who creates it. Changes to the creator's role or scope do not affect the API key's permissions. Only administrators can create organization-owned API keys.

| | API Key Type |

Select the purpose of the API key:

- CI/CD Integration: Authenticate CI/CD pipeline integrations.
- API Integration: Authenticate applications that access the OX API.
- IDE/CLI Integration: Authenticate IDE extensions or CLI tools.
- K8s Inspector/Runtime Sensor Integration: Authenticate Kubernetes Inspector and Runtime Sensor integrations.
- MCP Integration: Authenticate MCP integrations.
- VibeSec Agent: Authenticate VibeSec agents.

| | Assign role |

For organization-owned API keys, select the role that determines what actions the API key can perform in OX. The assigned role remains unchanged when the creator's role changes.

Personal API keys inherit the creator's role.

For information about available roles and their permissions, see the Roles documentation.

| | Assign scope |

For organization-owned API keys, select which applications the API key can access:

- Entire organization: Grants access to all applications in the organization.
- Custom: Limits access to applications that match the selected App Owners and Tags.

Personal API keys inherit the creator's scope.

| | Expiration Date | Select when the API key expires. After this date, the key can no longer be used to authenticate API requests. | 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:///api/apollo-gateway` * In **Headers** > **Authorization**, add the OX API key.
2. In the **Body** section, add query and click **Send**.
--- # 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 by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.ox.security/api-documentation/api-reference/ox-api-authentication.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. 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.