---
title: "Create credential"
method: POST
path: "/credentials"
tags: ["Credentials"]
---

# Create credential

`POST /credentials`

Create a new credential. The secret is returned once and never readable again.

## Request body

- union
  - BearerTokenCreateRequest — Create request for bearer_token credentials.
    - `api` APIReferenceRequest, required — Relaxed variant for request bodies where partial identification is allowed.
      - `catalog_api_id` string, nullable
      - `name` string
      - `vendor` string, required
      - `version` string
    - `name` string, required
    - `provider` string
    - `runtime_config` RuntimeConfig — Optional per-upstream-call overrides.
      - `headers` object, nullable
      - `query_params` object, nullable
    - `server_variables` object, nullable
    - `token` string, required
    - `type` 'bearer_token', required
  - ApiKeyCreateRequest — Create request for api_key credentials.
    - `api` APIReferenceRequest, required — Relaxed variant for request bodies where partial identification is allowed.
      - `catalog_api_id` string, nullable
      - `name` string
      - `vendor` string, required
      - `version` string
    - `field_name` string, required — Header or query-parameter name carrying the key.
    - `key` string, required — The API key secret. Stored encrypted; never returned after create.
    - `location` 'header' | 'query' | 'cookie', required — Where an API-key credential is injected into a request.
    - `name` string, required — Human-readable label for the credential.
    - `provider` string — Credential provider; 'static' for stored secrets.
    - `runtime_config` RuntimeConfig — Optional per-upstream-call overrides.
      - `headers` object, nullable
      - `query_params` object, nullable
    - `server_variables` object, nullable
    - `type` 'api_key', required
  - BasicAuthCreateRequest — Create request for basic credentials.
    - `api` APIReferenceRequest, required — Relaxed variant for request bodies where partial identification is allowed.
      - `catalog_api_id` string, nullable
      - `name` string
      - `vendor` string, required
      - `version` string
    - `name` string, required
    - `password` string, required
    - `provider` string
    - `runtime_config` RuntimeConfig — Optional per-upstream-call overrides.
      - `headers` object, nullable
      - `query_params` object, nullable
    - `server_variables` object, nullable
    - `type` 'basic', required
    - `username` string, required
  - OAuth2CreateRequest — Create request for oauth2 credentials. For managed providers (e.g. pipedream, direct_oauth2), token_url/client_id/client_secret are optional — the connect flow handles authentication without caller-supplied client details.
    - `api` APIReferenceRequest, required — Relaxed variant for request bodies where partial identification is allowed.
      - `catalog_api_id` string, nullable
      - `name` string
      - `vendor` string, required
      - `version` string
    - `authorize_url` string, nullable
    - `client_id` string, nullable
    - `client_secret` string, nullable
    - `grant_type` string
    - `name` string, required
    - `provider` string
    - `runtime_config` RuntimeConfig — Optional per-upstream-call overrides.
      - `headers` object, nullable
      - `query_params` object, nullable
    - `scopes` string[], nullable
    - `server_variables` object, nullable
    - `token_url` string, nullable
    - `type` 'oauth2', required
  - NoAuthCreateRequest — Create request for no_auth credentials. A no-auth credential carries no secret — it represents "this API is called without authentication". It still exists as a credential row so a toolkit binding (and its permission rules) can hang off it, and the broker resolves it as a no-op auth (see broker credential resolver / injection).
    - `api` APIReferenceRequest, required — Relaxed variant for request bodies where partial identification is allowed.
      - `catalog_api_id` string, nullable
      - `name` string
      - `vendor` string, required
      - `version` string
    - `name` string, required
    - `provider` string
    - `runtime_config` RuntimeConfig — Optional per-upstream-call overrides.
      - `headers` object, nullable
      - `query_params` object, nullable
    - `server_variables` object, nullable
    - `type` 'no_auth', required

## Response `201`

Successful Response

- CredentialCreateResponse — Create response: redacted + secret shown once.
  - `credential` CredentialRedactedResponse, required — Redacted credential response (for read/list/patch).
    - `active` boolean, required — Whether the credential is enabled for injection.
    - `api` APIReference, required — Identifies a target API — the strict (all-required) variant. Used in responses and as the canonical identity tuple.
      - `name` string, required
      - `vendor` string, required
      - `version` string, required
    - `catalog_api_id` string, nullable — Catalog identity slug of the target API (`domain[/sub-api]`), when recorded at create time. Display-only; null for older credentials.
    - `created_at` string, date-time, required — Creation timestamp (UTC).
    - `created_by` string, nullable — Identity that created the credential (its owner).
    - `credential_id` string, required — Stable credential identifier, prefixed `cred_`.
    - `details` object, nullable — Redacted, type-specific projection (hints/last-N chars; never the secret). For oauth2: client_id, token_url, grant_type (authorization_code | client_credentials), scopes, and — for authorization_code only — `connected`, whether the interactive sign-in completed and is still usable (null for other grants).
    - `name` string, required — Human-readable label.
    - `provider` string, required — Credential provider; 'static' for stored secrets.
    - `provider_account_ref` string, nullable — Opaque reference to the provider account, when applicable.
    - `server_variables` object, nullable — OpenAPI server-variable values for URL template substitution.
    - `type` 'bearer_token' | 'api_key' | 'basic' | 'oauth2' | 'no_auth', required — Wire-level credential type used by the provider abstraction.
    - `updated_at` string, date-time, nullable — Last update timestamp (UTC).
  - `secret` object, required

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `422` — Unprocessable Entity
- `500` — Internal Server Error
- `503` — Service Unavailable

## Changes

- **2026-07-31** `3746d110464c` — 6 info
  - added the new optional request property `oneOf[subschema #1: BearerTokenCreateRequest]/api/catalog_api_id`
  - added the new optional request property `oneOf[subschema #2: ApiKeyCreateRequest]/api/catalog_api_id`
  - added the new optional request property `oneOf[subschema #3: BasicAuthCreateRequest]/api/catalog_api_id`
  - added the new optional request property `oneOf[subschema #4: OAuth2CreateRequest]/api/catalog_api_id`
  - …2 more
- **2026-07-24** `7f8d4d76abcd` — 1 warning, 2 info
  - added the new `no_auth` enum value to the `credential/type` response property for the response status `201`
  - added `no_auth` mapping keys to the request discriminator
  - added `#/components/schemas/NoAuthCreateRequest` to the request body `oneOf` list
- **2026-07-23** `e7b87904bdbb` — 1 info
  - added the optional property `credential/created_by` to the response with the `201` status
- **2026-07-01** `d65fcba0d25a` — 4 breaking, 24 warning, 22 info
  - the request's body type/format changed from `object`/`` to ``/``
  - the `detail` response's property type/format changed from `array`/`` to `string`/`` for status `422`
  - removed the required property `id` from the response with the `201` status
  - removed the required property `label` from the response with the `201` status
  - …46 more
- …earlier changes not shown

[Full history](https://skmtc.dev/jentic/apis/jentic-control-plane-api/changes/credentials/post.md)

---

[API](https://skmtc.dev/jentic/apis/jentic-control-plane-api.md) · [All operations](https://skmtc.dev/jentic/apis/jentic-control-plane-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/jentic/jentic-control-plane-api/revisions/b2dc8a8290fa/schema)