> ## Documentation Index > Fetch the complete documentation index at: https://developers.soax.com/llms.txt > Use this file to discover all available pages before exploring further. # Create an API key > Create a new API key. To prevent privilege escalation, the new key's `scopes` must be a subset of the calling key's scopes, and `package_ids` (if provided) must be a subset of the calling key's package restriction. If `package_ids` is omitted, the new key inherits the calling key's restriction. The response includes the plaintext `secret` — this is the **only** time it is ever returned. Store it immediately in a secure location. Requires the `api-keys:write` scope. ## OpenAPI ````yaml api/openapi.json POST /v1/api-keys/ openapi: 3.1.0 info: title: SOAX API version: v1 description: >- Programmatic access to your SOAX account: manage proxy packages, generate connection strings, browse available locations, pull usage analytics, and manage API keys. All endpoints are served over HTTPS and return JSON. servers: - url: https://api.platform.soax.com security: - bearerAuth: [] tags: - name: API Keys description: >- Self-service management of the API keys used to authenticate with this API. - name: Packages description: >- Read proxy packages, build proxy connection strings, and rotate package passwords. - name: Locations description: >- Location reference data: tiers, countries, regions, cities, ISPs, ASNs, and ZIP codes. - name: Account description: Read-only account, credit, and subscription information. - name: Analytics description: Usage analytics for your proxy packages. paths: /v1/api-keys/: post: tags: - API Keys summary: Create a new API key for the authenticated customer description: >- Create a new API key. To prevent privilege escalation, the new key's `scopes` must be a subset of the calling key's scopes, and `package_ids` (if provided) must be a subset of the calling key's package restriction. If `package_ids` is omitted, the new key inherits the calling key's restriction. The response includes the plaintext `secret` — this is the **only** time it is ever returned. Store it immediately in a secure location. Requires the `api-keys:write` scope. operationId: create_api_key_v1_api_keys__post requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateApiKeyRequest' example: name: CI analytics reader scopes: - proxy:analytics:read package_ids: - b2f0c3d4-e5a6-4b7c-8d9e-0f1a2b3c4d5e required: true responses: '201': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/CreateApiKeyResponse' example: id: 7c2d9e0f-1a2b-4c3d-8e9f-a0b1c2d3e4f5 name: CI analytics reader scopes: - proxy:analytics:read package_ids: - b2f0c3d4-e5a6-4b7c-8d9e-0f1a2b3c4d5e secret: >- s_live_Qh1kT3examplenotarealsecretvalueXo9pW2zR8vY5uB0mN4cL7dS6fG1jK created_at: '2026-08-11T12:00:00Z' '400': description: >- A parameter value or combination is invalid. Service-level validation errors use the `error` key; endpoint-level checks use `detail`. Read `detail ?? error`. content: application/json: schema: type: object properties: detail: type: string error: type: string example: error: Requested scopes exceed the calling key's own scopes '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/ForbiddenScope' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' '429': $ref: '#/components/responses/RateLimited' components: schemas: CreateApiKeyRequest: properties: name: type: string title: Name description: >- Human-readable name for the key (shown in the dashboard and key listings). scopes: items: type: string type: array title: Scopes description: Scopes to grant. Must be a subset of the calling key's own scopes. package_ids: anyOf: - items: type: string type: array - type: 'null' title: Package Ids description: >- Optional list of package IDs the key is restricted to. Must be a subset of the calling key's own restriction. Omit to inherit the calling key's restriction; `null` on an unrestricted caller creates an unrestricted key. type: object required: - name - scopes title: CreateApiKeyRequest description: Request schema for POST /v1/api-keys endpoint. CreateApiKeyResponse: properties: id: type: string title: Id name: type: string title: Name scopes: items: type: string type: array title: Scopes package_ids: anyOf: - items: type: string type: array - type: 'null' title: Package Ids secret: type: string title: Secret created_at: type: string format: date-time title: Created At type: object required: - id - name - scopes - package_ids - secret - created_at title: CreateApiKeyResponse description: |- Response schema for POST /v1/api-keys endpoint. Includes the plaintext secret, which is only revealed at creation time and can never be retrieved again. The secret should be immediately stored by the client in a secure location. HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type type: object required: - loc - msg - type title: ValidationError responses: Unauthorized: description: Missing, invalid, or revoked API key. content: application/json: schema: type: object properties: detail: type: string example: detail: Invalid API key ForbiddenScope: description: The API key does not carry the scope this endpoint requires. content: application/json: schema: type: object properties: detail: type: string example: detail: 'Missing required scope: proxy:packages:read' RateLimited: description: >- Rate limit exceeded (5 requests/second per API key, 500 requests/minute per IP). The response includes `Retry-After` (seconds), `RateLimit-Limit`, `RateLimit-Remaining`, and `RateLimit-Reset` (Unix time) headers — wait `Retry-After` seconds and retry. content: application/json: schema: type: object properties: error: type: string example: error: 'Rate limit exceeded: 5 per 1 second' securitySchemes: bearerAuth: type: http scheme: bearer description: >- API key secret (starts with `s_live_`). Create keys in the dashboard under **Settings → API keys**, or via `POST /v1/api-keys/`. Send it as `Authorization: Bearer `. ````