> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudhumans.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a REST API credential

> Creates a REST API credential in a workspace and returns only its `credentialsId`. The credential stores a base URL plus optional headers and query params, encrypted, and no endpoint ever returns them.

To use it, put the returned `credentialsId` in the `options.credentialsId` of an HTTP Request block with **Update a flow**. The block then sends the credential's base URL, headers and query params without any secret appearing in the flow.

- Creating needs the workspace admin role (`403` otherwise).
- A `name` already used by another REST API credential is a `409`. Check **List REST API credentials** first and reuse one that fits.
- `baseUrl` must be an `http` or `https` URL with no `user:password@`, query string or fragment (`400` otherwise). Secrets go in `headers` or `queryParams`, never in the URL.



## OpenAPI

````yaml /api-reference/specs/controlled-flows/v1.json post /v1/credentials
openapi: 3.0.3
info:
  title: Controlled Flows API
  version: 1.0.0
  description: >-
    Read, build, validate and publish controlled flows and the tools agents
    call.
servers:
  - url: https://api.cloudhumans.com/typebot
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Workspaces
    description: The workspaces that hold your flows.
  - name: Flows
    description: >-
      Read, create, change, validate and publish flows. Writes land in the
      draft; only a publish makes them live.
  - name: Versions
    description: The saved versions of a flow, and restoring one.
  - name: Credentials
    description: >-
      REST API credentials that HTTP Request blocks send without exposing the
      secret in the flow.
paths:
  /v1/credentials:
    post:
      tags:
        - Credentials
      summary: Create a REST API credential
      description: >-
        Creates a REST API credential in a workspace and returns only its
        `credentialsId`. The credential stores a base URL plus optional headers
        and query params, encrypted, and no endpoint ever returns them.


        To use it, put the returned `credentialsId` in the
        `options.credentialsId` of an HTTP Request block with **Update a flow**.
        The block then sends the credential's base URL, headers and query params
        without any secret appearing in the flow.


        - Creating needs the workspace admin role (`403` otherwise).

        - A `name` already used by another REST API credential is a `409`. Check
        **List REST API credentials** first and reuse one that fits.

        - `baseUrl` must be an `http` or `https` URL with no `user:password@`,
        query string or fragment (`400` otherwise). Secrets go in `headers` or
        `queryParams`, never in the URL.
      operationId: createCredential
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - credentials
              description: The credential to create.
              properties:
                credentials:
                  type: object
                  required:
                    - type
                    - workspaceId
                    - name
                    - data
                  description: The REST API credential to create.
                  properties:
                    type:
                      type: string
                      enum:
                        - rest-api
                      description: >-
                        The kind of credential. Only `rest-api` is accepted; any
                        other value answers 400.
                    workspaceId:
                      type: string
                      description: >-
                        The workspace to create the credential in, e.g.
                        `clx1a2b3c4d5e6f7g8h9`. Get it from **List workspaces**.
                        A workspace your token cannot reach answers 404.
                    name:
                      type: string
                      description: >-
                        A label that identifies the credential in the workspace,
                        e.g. `Acme orders API`. It must not be used by another
                        credential of the same type (409). It is not a secret.
                    data:
                      type: object
                      required:
                        - baseUrl
                      description: >-
                        What the credential sends on every call. These values
                        are the customer's secrets.
                      properties:
                        baseUrl:
                          type: string
                          format: uri
                          description: >-
                            The base URL every request using this credential
                            goes to, e.g. `https://api.acme.com/v2`. Must be an
                            http or https URL with no `user:password@`, query
                            string or fragment (400 otherwise): secrets go in
                            `headers` or `queryParams`, never in the URL.
                        headers:
                          type: array
                          description: >-
                            Headers sent with every request, e.g.
                            `Authorization`. The values are secrets. Omit when
                            none are needed.
                          items:
                            $ref: '#/components/schemas/CredentialKeyValue'
                        queryParams:
                          type: array
                          description: >-
                            Query params appended to every request. The values
                            are secrets. Omit when none are needed.
                          items:
                            $ref: '#/components/schemas/CredentialKeyValue'
      responses:
        '200':
          description: >-
            The credential was created. Only its id is returned; the secret is
            never returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CredentialCreated'
        '400':
          description: >-
            The credential was refused and nothing was created. `message` says
            why: a `type` other than `rest-api`, a `baseUrl` that is not an http
            or https URL or carries `user:password@`, a query string or a
            fragment, or a header or query param with an empty key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing, expired or invalid credentials.
        '403':
          description: >-
            The user behind your token is not an ADMIN of the workspace. Only
            workspace admins can create REST API credentials. Nothing was
            created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: >-
            No such workspace, or none your token can reach — the two are
            deliberately indistinguishable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: >-
            A credential of this type already has this `name`. Nothing was
            created: pick another name, or reuse the existing one found with
            **List REST API credentials**.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit applied by the API gateway. Back off and retry.
components:
  schemas:
    CredentialKeyValue:
      type: object
      required:
        - key
        - value
      properties:
        key:
          type: string
          minLength: 1
          description: The header or query param name.
        value:
          type: string
          description: Its value. A secret.
      description: One header or query param the credential sends.
    CredentialCreated:
      type: object
      required:
        - credentialsId
      properties:
        credentialsId:
          type: string
          description: >-
            The new credential's id. Put it in an HTTP Request block's
            `options.credentialsId` with **Update a flow**.
      description: >-
        The credential was created. The secret it holds is write-only and is not
        returned.
    Error:
      type: object
      properties:
        message:
          type: string
          description: What went wrong.
        code:
          type: string
          description: Error code, e.g. `NOT_FOUND` or `BAD_REQUEST`.
        issues:
          type: array
          description: Per-field validation problems, present on a 400 for invalid input.
          items:
            type: object
            additionalProperties: true
      required:
        - message
        - code
      description: Something the caller needs to fix.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.