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

# Register Bre-B Key

> Registers the Bre-B key of a user so they can receive instant payments through Colombia's Bre-B system. Each user can have a single key.

#### Request

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| Authorization | Header | Yes | `Bearer <access_token>` obtained from **POST /api/v1/client/token**. |
| user_id | Path | Yes | User who owns the key. |

#### Request Body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| key | string | Yes | Bre-B key of the user (e.g. an alias such as `@MYKEY`, phone number or document). |
| idempotencyKey | string | No | Unique value to safely retry the request. |

#### Response

| Field | Description |
| --- | --- |
| userId | Owner of the key. |
| key | Registered key. |
| provider | Provider that registered the key. |
| idempotencyKey | Value sent in the request, if any. |
| providerResponse | Raw confirmation from the provider. |

#### Errors

| Status | Code | When |
| --- | --- | --- |
| 409 | `BREB_KEY_ALREADY_REGISTERED` | The user already has a key. |
| 422 | `BREB_IDENTITY_MISMATCH`, `BREB_KEY_NOT_FOUND_OR_INACTIVE`, `BREB_USER_IDENTITY_MISSING`, ... | The key does not belong to the user's identity, is inactive, or the user's identity data is incomplete. |
| 502 | `BREB_PROVIDER_UNAVAILABLE` | The provider could not be reached; retry later. |



## OpenAPI

````yaml /stack/openapi.json post /api/v1/admin/users/{user_id}/breb/keys/register
openapi: 3.1.0
info:
  title: Kravata Stack API
  version: '2.0'
  description: >-
    Kravata Stack API: users, accounts, custody wallets, liquidity ramps and
    fiat payments.
servers:
  - url: https://test-api-kore.kravata.co
    description: Test
  - url: https://partners-api.kravata.co
    description: Production (mTLS + IP allowlist)
security:
  - bearerAuth: []
tags:
  - name: Authentication
  - name: Users
  - name: Accounts
  - name: Earn
  - name: Custody
  - name: Liquidity Ramps
  - name: Payments
  - name: Webhooks
paths:
  /api/v1/admin/users/{user_id}/breb/keys/register:
    post:
      tags:
        - Payments
      summary: Register Bre-B Key
      description: >-
        Registers the Bre-B key of a user so they can receive instant payments
        through Colombia's Bre-B system. Each user can have a single key.


        #### Request


        | Field | Type | Required | Description |

        | --- | --- | --- | --- |

        | Authorization | Header | Yes | `Bearer <access_token>` obtained from
        **POST /api/v1/client/token**. |

        | user_id | Path | Yes | User who owns the key. |


        #### Request Body


        | Field | Type | Required | Description |

        | --- | --- | --- | --- |

        | key | string | Yes | Bre-B key of the user (e.g. an alias such as
        `@MYKEY`, phone number or document). |

        | idempotencyKey | string | No | Unique value to safely retry the
        request. |


        #### Response


        | Field | Description |

        | --- | --- |

        | userId | Owner of the key. |

        | key | Registered key. |

        | provider | Provider that registered the key. |

        | idempotencyKey | Value sent in the request, if any. |

        | providerResponse | Raw confirmation from the provider. |


        #### Errors


        | Status | Code | When |

        | --- | --- | --- |

        | 409 | `BREB_KEY_ALREADY_REGISTERED` | The user already has a key. |

        | 422 | `BREB_IDENTITY_MISMATCH`, `BREB_KEY_NOT_FOUND_OR_INACTIVE`,
        `BREB_USER_IDENTITY_MISSING`, ... | The key does not belong to the
        user's identity, is inactive, or the user's identity data is incomplete.
        |

        | 502 | `BREB_PROVIDER_UNAVAILABLE` | The provider could not be reached;
        retry later. |
      operationId: register-bre-b-key
      parameters:
        - name: user_id
          in: path
          required: true
          description: ''
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                key:
                  type: string
                idempotencyKey:
                  type: string
            example:
              key: '@MYKEY'
              idempotencyKey: reg-key-001
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  userId:
                    type: string
                  key:
                    type: string
                  provider:
                    type: string
                  idempotencyKey:
                    type: string
                  providerResponse:
                    type: object
                    properties: {}
              examples:
                key-registered:
                  summary: Key registered
                  value:
                    userId: e097845b-20b1-4805-9708-740cbcf5d524
                    key: '@MYKEY'
                    provider: powwi
                    idempotencyKey: reg-key-001
                    providerResponse: {}
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Access token from POST /api/v1/client/token.

````