Register Public-Key Credential | AgentMail

from agentmail import AgentMail
from agentmail.api_keys import PublicJwk
client = AgentMail(
    api_key="YOUR_TOKEN_HERE",
)
client.api_keys.create_public_key(
    public_key=PublicJwk(
        kty="EC",
        crv="P-256",
        x="blackcurrant...............................",
        y="blackcurrant...............................",
    ),
)

{
  "api_key_id": "d5e9c84f-c2b2-4bf4-b4b0-7ffd7a9ffc32",
  "type": "public_key",
  "name": "name",
  "public_key": {
    "jwk": {
      "kty": "EC",
      "crv": "P-256",
      "x": "blackcurrant...............................",
      "y": "blackcurrant..............................."
    },
    "fingerprint": "blackcurrant..............................."
  },
  "scope": {
    "type": "organization"
  },
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z",
  "expires_at": "2024-01-15T09:30:00Z",
  "revoked_at": "2024-01-15T09:30:00Z"
}

Register a public P-256 JWK using an existing AgentMail bearer API key with api_key_create. Re-registering the same JWK creates a new credential ID; it does not replace or recover an earlier credential. The private key must never be sent to AgentMail.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Request

This endpoint expects an object.

public_keyobjectRequired

A public P-256 JWK. The object accepts exactly kty, crv, x, and y. Private key material such as d, embedded key IDs, and all other members are rejected. The server also rejects coordinates that are not a point on P-256.

namestringOptional1-256 characters

Defaults to AgentID key {first eight fingerprint characters}.

scopeobjectOptional

Omit to inherit the registering bearer key's exact scope. An explicit scope must be the caller's scope or a live descendant.

expires_atdatetimeOptional

Future absolute expiry. Omit to inherit the registering bearer key's expiry. A child credential cannot outlive its creator.

Response

This endpoint returns an object.

api_key_idUUID

Server-generated credential ID. Store this value as the signing key’s kid.

type"public_key"

Server-owned credential discriminator. Callers cannot select or update it.

namestring

Human-readable credential name.

public_keyobject

Registered public key material and its server-computed RFC 7638 thumbprint.

scopeobject

The immutable scope in which a public-key credential can approve AgentID sign-in.

created_atdatetime

updated_atdatetime

expires_atdatetimeOptional

Immutable absolute expiry. Omitted when the credential does not expire.

revoked_atdatetimeOptional

Present when organization-wide revoke-all invalidated this credential generation.

Errors

400

Validation Error

409

Conflict Error