# SigID Public API policy

The canonical API origin is https://auth.sigid.org. Start with the
[public OpenAPI document](https://auth.sigid.org/openapi.json),
[API explorer](https://auth.sigid.org/api/docs), and
[authentication guide](https://www.sigid.org/auth.md).
GET https://auth.sigid.org/api/v1/capabilities is a public, read-only endpoint
for discovering enabled features without creating an account.

## JSON errors

Ordinary API errors use RFC 9457 application/problem+json with type, title,
status, and detail. SigID extensions can include error, error_description, and
resolution hints. Unknown /api/* routes also return this structured format.
OAuth, OpenID4VC, and SCIM endpoints retain their protocol-specific error
contracts. Inspect Content-Type and the documented response schema.

For a 400, correct the request using OpenAPI. For a 401, acquire or refresh a
valid credential. For a 403, check the required scope, tenant, and policy. For
a 404, verify the origin, path, and resource identifier. Retry writes only when
their documented idempotency behavior makes the retry safe. Record x-request-id
for troubleshooting; never record credentials.

## Rate limits

Rate-limited API responses carry Retry-After in seconds on HTTP 429. Wait at
least that long before retrying. Successful and unsuccessful requests passing
through the global API limiter also carry quota hints; a more specific
downstream limiter may supply its own policy instead.

SigID uses the structured fields in
[IETF draft-ietf-httpapi-ratelimit-headers-11](https://datatracker.ietf.org/doc/html/draft-ietf-httpapi-ratelimit-headers-11):

```http
RateLimit-Policy: "global";q=500;w=3
RateLimit: "global";r=499;t=1
```

This example describes a quota q over window w seconds and remaining allowance
r over an effective window t seconds. Actual values depend on deployment and
request policy. These fields are an Internet-Draft, not a published RFC; parse
them as Structured Fields, ignore unknown parameters, and prefer Retry-After
when present. Quota hints are advisory and do not guarantee future access.
Static website assets have no invented API quota. Cross-origin API clients can
read RateLimit, RateLimit-Policy, Retry-After, and x-request-id through CORS on
permitted origins and public metadata routes.

## Versioning and deprecation

The stable public HTTP contract is URL-versioned under /api/v1/*. OAuth and OIDC
endpoints retain their protocol-standard paths. Additions within a published
API major version preserve existing request, response, status, and error
contracts. The OpenAPI document is the canonical operation inventory.

When an operation is deprecated, SigID publishes its replacement and migration
guidance in the OpenAPI description and changelog and sends Deprecation using
RFC 9745's Structured Field Date syntax. Once removal is scheduled, Sunset
uses the HTTP-date syntax of RFC 8594, and a Link with rel="deprecation" points
to migration guidance. Removal requires the next major API version and a
product major release. No arbitrary sunset date is assigned to active APIs.

Product Semantic Versioning and API path versions are distinct: a compatible
product release can continue serving /api/v1. See the
[SigID API and SDK reference](https://docs.sigid.org/reference/api-sdk-reference/)
for integration details. Deprecation notices link to the applicable migration
guidance when a replacement is announced.