---
title: "Register a provider"
method: POST
path: "/admin/providers"
tags: ["admin"]
---

# Register a provider

`POST /admin/providers`

Hot-registers a provider definition in the catalog. Accepts JSON or YAML.

## Request body

- Provider
  - `auth_methods` AuthSpec[]
    - `authenticated_request` AuthenticatedRequest — AuthenticatedRequest declares a single probe request used to validate freshly-submitted credentials against the upstream API. The path is expanded against the merged input vars (so multi-step providers can reference fields like {workspace_region}).
      - `identity` object — Identity maps trait names to gjson paths into the probe response body. The extracted values land on Connection.Metadata.identity, mirroring Kratos's identity-traits pattern so /done can render "Connected as john@example.com" with an avatar.
      - `method` string
      - `path` string
    - `authorization_url` string — AuthorizationURL is the OAuth2 authorization endpoint. Consumed by oauth2_code. May contain {var} template placeholders that the pre-flow UI fills in.
    - `callback_path` string — CallbackPath is appended to the deployment's public_url to form the OAuth callback URL. Defaults to "/oauth/callback". Path differs from "/flows/..." because httprouter v1 can't mix static "callback" with the named ":id" parameter under the same prefix.
    - `display_name` string — DisplayName is the human-readable label shown on the choose_method screen. Falls back to ID when empty.
    - `header_format` string — HeaderFormat customises the upstream Authorization header. Default is "Bearer {{.value}}" (Stripe, Slack, Google all use Bearer). GitHub overrides with "token {{.value}}". Templating: only {{.value}} is supported.
    - `id` string — ID is the method discriminator used by the flow engine (e.g. "oauth", "pat"). Unique per provider.
    - `scopes` string[] — Scopes is the OAuth2 scope list. Consumed by oauth2_code.
    - `strategy` string
    - `token_url` string — TokenURL is the OAuth2 token endpoint. Consumed by oauth2_code. May contain {var} placeholders.
    - `ui` UISpec[] — UI declares the provider's pre-flow form (e.g. Intercom region select, Stripe api_key entry). Empty for providers that go directly to OAuth.
      - `label` string
      - `name` string
      - `options` UIOption[]
        - `default` boolean
        - `label` string
        - `value` string
      - `required` boolean
      - `step` integer — Step groups fields into multi-step flows. Default 0 = single step.
      - `type` string
  - `display_name` string
  - `id` string
  - `logo_url` string
  - `proxy` ProxySpec — BaseURL and an optional RateLimit. A future BaseURLFromToken hint (Salesforce-style — instance_url captured at OAuth time already lands in Connection.Metadata) may follow.
    - `base_url` string — BaseURL is the upstream API root. May contain {var} template placeholders that get substituted from Connection.Metadata at proxy time (e.g. https://api.{region}.intercom.io).
    - `rate_limit` RateLimitSpec
      - `burst` integer — Burst is the maximum burst size (defaults to RPS).
      - `rps` number, double — RPS is requests-per-second.

## Response `200`

createProvider is the 200 response for POST /admin/providers.

- CreateProviderResponse
  - `id` string
  - `registered` boolean

## Other responses

- `400` — errorGeneric wraps the error model as a response.
- `503` — errorGeneric wraps the error model as a response.

---

[API](https://skmtc.net/hintoric/apis/contains-the-generated-openapi-specification-for-hekate.md) · [All operations](https://skmtc.net/hintoric/apis/contains-the-generated-openapi-specification-for-hekate/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/hintoric/contains-the-generated-openapi-specification-for-hekate/revisions/72bd83b55019/schema)