> ## Documentation Index
> Fetch the complete documentation index at: https://docs.baseten.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Register an API key

> Attach a caller-supplied API key to a Frontier Gateway group so downstream consumers can continue using a key they already issued.

Register a caller-supplied API key against an existing group. This exists for white-label deployments where you already mint keys for your end users and want Baseten inference under the hood without forcing them to rotate.

The registered key inherits the group's full live model set and effective limits, exactly like a key produced by [Create an API key](/reference/gateway/api-keys/create-an-api-key). Baseten stores only the hashed key; once registered, the plaintext value is unrecoverable from our side.

### Request signing

This endpoint accepts a key you generated, so Baseten verifies that each request came from you. Sign the request body with an Ed25519 private key; Baseten checks the signature against a public key held for your workspace. Requests without a valid signature return `400 Bad Request`.

Before your first call, generate an Ed25519 keypair and register the public key with Baseten:

```bash theme={"system"}
openssl genpkey -algorithm Ed25519 -out priv.pem
openssl pkey -in priv.pem -pubout -outform DER | tail -c 32 | base64
```

The second command prints the 32-byte public key as base64. Send it to Baseten to store for your workspace; until a key is on file, every call returns `400 Bad Request`. Keep `priv.pem` secret.

Sign the **exact bytes of the JSON body you send**, base64-encode the signature, and pass it in the `X-Baseten-Signature` header. Re-serializing the body before signing (different key order or whitespace) breaks verification, so sign the precise string you send.

### Key requirements

The `key` value you submit must satisfy these constraints. The endpoint returns `400 Bad Request` if any check fails:

| Constraint | Rule                                                                                                           |
| ---------- | -------------------------------------------------------------------------------------------------------------- |
| Length     | Between 32 and 128 characters, inclusive.                                                                      |
| Complexity | Shannon entropy of at least 3.0 bits per character. Any securely-generated random key satisfies this.          |
| Uniqueness | The first 16 characters become the key's stored `prefix` and must not already be registered in your workspace. |

Generate keys with a cryptographically secure random source on your side and bring them to this endpoint. Baseten does not return a generated key from this call.

### Authentication

<ParamField header="X-Baseten-Signature" type="string" required>
  Base64-encoded Ed25519 signature of the raw request body, produced with your workspace's private key. See [Request signing](#request-signing). A missing or invalid signature returns `400 Bad Request`.
</ParamField>

### Errors

| Status            | Meaning                                                                                                                                                   |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400 Bad Request` | The supplied `key` failed length, complexity, or uniqueness validation.                                                                                   |
| `400 Bad Request` | `Signature verification failed`: the `X-Baseten-Signature` header was missing, wasn't valid base64, or didn't verify against your workspace's public key. |
| `400 Bad Request` | `Must configure a public key before registering API keys`: no Ed25519 public key is on file for your workspace. See [Request signing](#request-signing).  |
| `403 Forbidden`   | The group exists but isn't in your workspace, or the caller doesn't have management scope.                                                                |
| `404 Not Found`   | No group with this `id` in your workspace, or it has been deleted.                                                                                        |

<RequestExample>
  ```bash curl theme={"system"}
  BODY='{"name":"acme-prod-key-1","key":"<your-securely-generated-api-key>"}'
  SIGNATURE=$(printf '%s' "$BODY" | openssl pkeyutl -sign -inkey priv.pem -rawin | openssl base64 -A)

  curl --request POST \
    --url https://api.baseten.co/v1/gateway/groups/abc123hash/api_keys/register \
    --header "Authorization: Api-Key $BASETEN_API_KEY" \
    --header "Content-Type: application/json" \
    --header "X-Baseten-Signature: $SIGNATURE" \
    --data "$BODY"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={"system"}
  {
    "ok": true
  }
  ```
</ResponseExample>


## OpenAPI

````yaml post /v1/gateway/groups/{group_id}/api_keys/register
openapi: 3.1.0
info:
  description: REST API for management of Baseten resources
  title: Baseten management API
  version: 1.0.0
servers:
  - url: https://api.baseten.co
security:
  - BearerAuth: []
paths:
  /v1/gateway/groups/{group_id}/api_keys/register:
    parameters:
      - $ref: '#/components/parameters/group_id'
    post:
      summary: Registers an API key for a group
      description: Registers a Gateway API key with the provided value and name.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegisterAPIKeyRequestV1'
        required: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegisterAPIKeyResponseV1'
      x-codeSamples:
        - lang: bash
          source: >-
            curl --request POST \

            --url
            https://api.baseten.co/v1/gateway/groups/{group_id}/api_keys/register
            \

            --header "Authorization: Bearer $BASETEN_API_KEY" \

            --data '{
              "name": "my-model-api-key",
              "key": "my-secure-api-key-value"
            }'
        - lang: python
          source: >-
            import requests

            import os

            API_KEY = os.environ.get("BASETEN_API_KEY", "<YOUR_API_KEY>")

            url =
            "https://api.baseten.co/v1/gateway/groups/{group_id}/api_keys/register"


            headers = {"Authorization": f"Bearer {API_KEY}"}


            response = requests.request(
                "POST",
                url,
                headers=headers,
                json={'name': 'my-model-api-key', 'key': 'my-secure-api-key-value'}
            )


            print(response.text)
components:
  parameters:
    group_id:
      schema:
        type: string
      name: group_id
      in: path
      required: true
  schemas:
    RegisterAPIKeyRequestV1:
      description: >-
        Request to register a caller-supplied API key against an existing
        FederatedGroup.
      properties:
        name:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: Optional name for the Model API key
          examples:
            - my-model-api-key
          title: Name
        key:
          description: Value of the API key to register
          examples:
            - my-secure-api-key-value
          title: Key
          type: string
      required:
        - key
      title: RegisterAPIKeyRequestV1
      type: object
    RegisterAPIKeyResponseV1:
      properties:
        ok:
          description: Whether the registration was successful
          title: Ok
          type: boolean
      required:
        - ok
      title: RegisterAPIKeyResponseV1
      type: object
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: >-
        Send `Authorization: Bearer <api_key>`. The legacy `Authorization:
        Api-Key <api_key>` scheme is also accepted.

````