---
title: "Create Federation Rule"
method: POST
path: "/api/v1/keys/{key_id}/federation-rules"
tags: ["keys"]
---

# Create Federation Rule

`POST /api/v1/keys/{key_id}/federation-rules`

## Request

- The document declares no server URL.
- Auth: one of:
  - API key in header `Otari-Key`
  - API key in header `x-api-key`

Let an OpenID Connect identity token authenticate as this key, in place of its secret.

The issuer must be one of the deployment's ``federation_issuers``, else 400. A token authenticates when it is
signed by that issuer, its ``aud`` contains ``audience``, and it carries the rule's ``subject`` and verified
``email``, whichever the rule sets. A rule naming the identity of an existing rule answers 409: the same issuer,
audience, subject and email on this key, or on another key the same issuer and audience with a subject or email
in common and no contradicting value.

## Path parameters

- `key_id` string, required

## Request body

- FederationRuleCreate: An OpenID Connect identity that may authenticate as the key, in place of its secret. A token matches when it is signed by ``issuer``, names ``audience`` among its audiences, and carries each of ``subject`` and ``email`` that the rule sets; an email matches only when the token marks it verified. At least one of the two is required.
  - `audience` string, required: A value the token's 'aud' must contain.
  - `email` string, nullable: The token's verified 'email', when the rule names one. Compared without regard to case.
  - `issuer` string, required: The token's 'iss', one of the deployment's federation_issuers.
  - `subject` string, nullable: The token's 'sub', when the rule names one.

## Response `201`

Successful Response

- FederationRulePublic: A federation rule of an API key.
  - `api_key_id` string, required
  - `audience` string, required
  - `created_at` string, date-time, required
  - `email` string, nullable, required
  - `id` string, required
  - `issuer` string, required
  - `subject` string, nullable, required

## Other responses

- `422`: Validation Error

## Changes

- **2026-10-17** `63724f6891aa`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/mozilla-ai/apis/otari/changes/api/v1/keys/:key_id/federation-rules/post.md)

---

[API](https://skmtc.dev/mozilla-ai/apis/otari.md) · [All operations](https://skmtc.dev/mozilla-ai/apis/otari/llms.txt) · [OpenAPI document](https://skmtc.dev/mozilla-ai/apis/otari/revisions/b7bdd49b4752?raw)