> ## Documentation Index > Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt > Use this file to discover all available pages before exploring further. # Create API key > Use the OneSignal API to create a new Rich Authentication Token (App API Key) for a specific app. This guide explains how to authenticate with the Organization API key and configure optional IP allowlists using CIDR notation. ## Overview Use this API to create a new **App API Key** (also called a **Rich Authentication Token**) for a specific OneSignal app. These keys are used to authenticate API requests at the app level and offer enhanced security features, including optional IP allowlisting. For background on different OneSignal API keys, see [Keys & IDs](/docs/en/keys-and-ids). *** ## How to use this API Use your [Organization API Key](/docs/en/keys-and-ids#organization-api-key), to authenticate. This key is **different** from the standard REST API key. ### IP allowlisting By default, the API key will not be restricted to any specific IP addresses. To enable IP allowlisting, you need to set the `ip_allowlist_mode` parameter to `explicit` and provide a list of allowed IP addresses in the `ip_allowlist` parameter. If you want to set the explicit range of IPs that can use this API key, add them by setting `ip_allowlist_mode` to `explicit` and in `ip_allowlist` add the IPs in CIDRs notation as an array of string values. *** ## OpenAPI ````yaml POST /apps/{app_id}/auth/tokens openapi: 3.1.0 info: title: api.onesignal.com version: '11.6' servers: - url: https://api.onesignal.com security: - {} paths: /apps/{app_id}/auth/tokens: post: summary: Create API key description: >- Use the OneSignal API to create a new Rich Authentication Token (App API Key) for a specific app. This guide explains how to authenticate with the Organization API key and configure optional IP allowlists using CIDR notation. operationId: create-api-key parameters: - name: app_id in: path description: >- Your OneSignal App ID in UUID v4 format. See [Keys & IDs](/docs/en/keys-and-ids). schema: type: string default: YOUR_APP_ID required: true - name: Content-Type in: header required: true schema: type: string default: application/json - name: Authorization in: header description: >- Your Organization API key with prefix `Key `. See [Keys & IDs](/docs/en/keys-and-ids). required: true schema: type: string default: Key YOUR_ORGANIZATION_API_KEY requestBody: content: application/json: schema: type: object required: - name properties: name: type: string description: >- An internal name you set to help organize and track API keys (Rich Authentication Tokens). Maximum 128 characters. ip_allowlist_mode: type: string description: >- Defaults to `disabled`, can be set to `explicit`. If set to `explicit`, a list of network addresses in the form of CIDRs has to be specified in the `ip_allowlist` parameter. enum: - disabled - explicit ip_allowlist: type: array description: >- An array of allowed networks in CIDRs notation. Only IPs in those ranges will be permitted to use the API key. items: type: string responses: '200': description: >- The newly-created API key token. `token_id` and `formatted_token` are populated; `formatted_token` is the secret and is returned ONCE — store it now or rotate later. content: application/json: schema: $ref: '#/components/schemas/ApiKeyToken' '400': description: '400' content: application/json: examples: Result: value: '{}' schema: type: object properties: {} '403': description: Forbidden. Your organization permissions do not allow this action. content: application/json: schema: $ref: '#/components/schemas/BasicErrorResponse' example: errors: - Current organization permissions do not allow this action. '404': description: App not found. content: application/json: schema: $ref: '#/components/schemas/BasicErrorResponse' example: errors: - App not found '429': description: >- Rate limit exceeded. Wait the number of seconds in the `Retry-After` header before retrying. headers: Retry-After: description: >- Number of seconds to wait before retrying the request. Always emitted on 429 responses. schema: type: integer minimum: 0 content: application/json: schema: $ref: '#/components/schemas/BasicErrorResponse' example: errors: - API rate limit exceeded '503': description: >- Service temporarily unavailable. Retry after a short backoff. The body may be empty or non-JSON in some failure modes. headers: Retry-After: description: >- Number of seconds to wait before retrying. Optional — may be absent when the response is generated upstream. schema: type: integer minimum: 0 content: application/json: schema: $ref: '#/components/schemas/BasicErrorResponse' example: errors: - Service temporarily unavailable deprecated: false components: schemas: ApiKeyToken: type: object description: >- An API Key Token record (Rich Authentication Token). Different operations return different subsets of these fields: - **GET tokens** lists every field except `formatted_token`. - **POST tokens** (create) returns `token_id` and `formatted_token`. - **POST tokens/{id}/rotate** returns `formatted_token` only. - **PATCH tokens/{id}** updates the record; the response body is currently empty (consumers should re-fetch via GET). `formatted_token` is the actual REST API Key and is shown ONCE — OneSignal does not store it. Keep it secret. properties: token_id: type: string format: uuid description: >- OneSignal-generated identifier for this API key. NOT the API key itself — use this to manage the key in subsequent calls. name: type: string description: >- Internal name set when the key was created or last updated. Maximum 128 characters. ip_allowlist_mode: type: string enum: - disabled - explicit description: >- When `explicit`, only requests from IP addresses matching `ip_allowlist` may use this key. Defaults to `disabled`. ip_allowlist: type: array items: type: string description: >- Allowed CIDR ranges. Only enforced when `ip_allowlist_mode` is `explicit`. created_at: type: string format: date-time description: ISO-8601 timestamp when the key was created. updated_at: type: string format: date-time description: ISO-8601 timestamp when the key was last updated. formatted_token: type: string description: >- The actual Rich Authentication Token (REST API Key). Returned in plaintext ONLY by the create and rotate endpoints, and ONLY immediately after that call. OneSignal does not store the secret — if you lose it, you must rotate the key. See [Rotate API Key](/reference/rotate-api-key). BasicErrorResponse: type: object properties: errors: type: array items: type: string description: One or more human-readable error messages. success: type: boolean description: >- Present (and `false`) on some endpoints (notifications, templates, segments). Not emitted by every endpoint. reference: type: array items: type: string description: >- Documentation URL fragments related to the error. Only emitted by the API-key auth error helpers. ````