Claves de API de la Organization

Gestiona claves de API a nivel de la Organization desde el Dashboard — crea, lista, inspecciona alcances y revoca claves que actúan en todos los Merchants de la organización.

Estos endpoints respaldan la pantalla de claves de API de la Organization. Una clave de la Organization (sk_live_org_… / pk_live_org_…) puede actuar en todos los Merchants de la organización, indicando el Merchant de destino con merchant_id en cada llamada — a diferencia de una clave de Merchant, que está restringida a uno solo.

El secreto completo se muestra únicamente en la creación; después, una clave se identifica por su prefijo no secreto. La revocación es inmediata y permanente.

Estos endpoints impulsan la interfaz del Tokeflow Dashboard a nivel de la Organization. Están autenticados por sesión (JWT bearer) — el token proviene de iniciar sesión en el Dashboard, no de una clave de API sk_/pk_. Las solicitudes también incluyen el header x-organization-id, y el usuario que inició sesión debe ser miembro de esa Organization.

El objeto de clave de API

Devuelto por los endpoints de listado y de recuperación de esta página.

Campo	Tipo	Descripción
`id`	string	Identificador único de la clave de API.
`entity_type`	string	Tipo de entidad (organization o merchant).
`entity_id`	string	ID de la entidad.
`name`	string	Nombre legible de la clave de API.
`key_prefix`	string	Prefijo de la clave para identificación.
`scopes`	array	Alcances/permisos de la clave de API.
`allowed_ips`	array \| null	Direcciones IP permitidas.
`is_active`	boolean	Indica si la clave de API está activa.
`expires_at`	string \| null	Fecha de expiración. (ISO 8601 UTC).
`last_used_at`	string \| null	Última vez que se usó la clave. (ISO 8601 UTC).
`created_at`	string	Marca de tiempo de creación. (ISO 8601 UTC).
`key_hash`	string	—

Endpoints

GET`/api/v1/org/api-keys`

Org

Auth: Dashboard session (JWT bearer). Se requiere membresía de la Organization.

Lista las claves de API del Merchant.

Parámetros de consulta

Campo	Tipo	Obligatorio	Descripción
`page`	number	No	Número de página (indexado desde 1). Predeterminado `1`, mín. `1`.
`limit`	number	No	Número de elementos por página. Predeterminado `20`, mín. `1`, máx. `100`.

Ejemplo de solicitud

curl -G https://api.tokeflow.com/api/v1/org/api-keys \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-organization-id: org_4b21e7c3" \
  --data-urlencode "page=1" \
  --data-urlencode "limit=20"

Ejemplo de respuesta — 200

{
  "data": [
    {
      "id": "obj_1a2b3c4d",
      "entity_type": "standard",
      "entity_id": "string",
      "name": "Acme Store",
      "key_prefix": "sk_live_mer_7d21",
      "scopes": [
        "string"
      ],
      "allowed_ips": [
        "203.0.113.10"
      ],
      "is_active": true,
      "expires_at": "2026-01-15T12:30:00.000Z",
      "last_used_at": "2026-01-15T12:30:00.000Z",
      "created_at": "2026-01-15T12:30:00.000Z",
      "key_hash": "sk_live_mer_7d21"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 42,
    "total_pages": 3,
    "has_next": true,
    "has_prev": false
  }
}

POST`/api/v1/org/api-keys`

Org

Auth: Dashboard session (JWT bearer). Se requiere membresía de la Organization.

Crea una nueva clave de API para el Merchant.

Campos de la solicitud

Campo	Tipo	Obligatorio	Descripción
`entity_type`	string	No	Tipo de entidad a la que pertenece la clave de API. Uno de `organization`, `merchant`.
`entity_id`	string	No	ID de la entidad (organization o merchant).
`name`	string	Sí	Nombre legible de la clave de API.
`scopes`	array	Sí	—
`allowed_ips`	array	Sí	—
`expires_at`	string	No	Fecha de expiración de la clave de API (ISO 8601).
`key_type`	string	No	Tipo de clave de API - secret o public. Uno de `secret`, `public`.

Ejemplo de solicitud

curl -X POST https://api.tokeflow.com/api/v1/org/api-keys \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-organization-id: org_4b21e7c3" \
  -H "Content-Type: application/json" \
  -d '{
    "entity_type": "merchant",
    "entity_id": "mrc_123",
    "name": "Production Key Store XPTO",
    "scopes": [
      [
        "transactions:write",
        "transactions:read"
      ]
    ],
    "allowed_ips": [
      [
        "1.2.3.4",
        "192.168.0.0/16",
        "2001:db8::/32"
      ]
    ],
    "expires_at": "2026-01-15T12:30:00.000Z",
    "key_type": "secret"
  }'

Ejemplo de respuesta — 201

{
  "id": "obj_1a2b3c4d",
  "entity_type": "standard",
  "entity_id": "string",
  "name": "Acme Store",
  "key_prefix": "sk_live_mer_7d21",
  "scopes": [
    "string"
  ],
  "allowed_ips": [
    "203.0.113.10"
  ],
  "is_active": true,
  "expires_at": "2026-01-15T12:30:00.000Z",
  "last_used_at": "2026-01-15T12:30:00.000Z",
  "created_at": "2026-01-15T12:30:00.000Z",
  "api_key": "sk_live_mer_98765...",
  "key_hash": "sk_live_mer_7d21"
}

GET`/api/v1/org/api-keys/scopes`

Org

Auth: Dashboard session (JWT bearer). Se requiere membresía de la Organization.

Devuelve los alcances que se pueden asignar a las claves de API. Filtra por entity_type y/o key_type.

Parámetros de consulta

Campo	Tipo	Obligatorio	Descripción
`entity_type`	string	Sí	—
`key_type`	string	Sí	—

Ejemplo de solicitud

curl -G https://api.tokeflow.com/api/v1/org/api-keys/scopes \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-organization-id: org_4b21e7c3" \
  --data-urlencode "entity_type=standard" \
  --data-urlencode "key_type=sk_live_mer_7d21"

GET`/api/v1/org/api-keys/:id`

Org

Auth: Dashboard session (JWT bearer). Se requiere membresía de la Organization.

Obtiene una clave de API por ID.

Parámetros de ruta

Campo	Tipo	Obligatorio	Descripción
`id`	string	Sí	API Key ID

Ejemplo de solicitud

curl https://api.tokeflow.com/api/v1/org/api-keys/obj_1a2b3c4d \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-organization-id: org_4b21e7c3"

Ejemplo de respuesta — 200

{
  "id": "obj_1a2b3c4d",
  "entity_type": "standard",
  "entity_id": "string",
  "name": "Acme Store",
  "key_prefix": "sk_live_mer_7d21",
  "scopes": [
    "string"
  ],
  "allowed_ips": [
    "203.0.113.10"
  ],
  "is_active": true,
  "expires_at": "2026-01-15T12:30:00.000Z",
  "last_used_at": "2026-01-15T12:30:00.000Z",
  "created_at": "2026-01-15T12:30:00.000Z",
  "key_hash": "sk_live_mer_7d21"
}

PATCH`/api/v1/org/api-keys/:id`

Org

Auth: Dashboard session (JWT bearer). Se requiere membresía de la Organization.

Actualiza una clave de API (activa/desactiva).

Parámetros de ruta

Campo	Tipo	Obligatorio	Descripción
`id`	string	Sí	API Key ID

Campos de la solicitud

Campo	Tipo	Obligatorio	Descripción
`is_active`	boolean	No	Indica si la clave de API está activa.

Ejemplo de solicitud

curl -X PATCH https://api.tokeflow.com/api/v1/org/api-keys/obj_1a2b3c4d \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-organization-id: org_4b21e7c3" \
  -H "Content-Type: application/json" \
  -d '{
    "is_active": false
  }'

Ejemplo de respuesta — 200

{
  "id": "obj_1a2b3c4d",
  "entity_type": "standard",
  "entity_id": "string",
  "name": "Acme Store",
  "key_prefix": "sk_live_mer_7d21",
  "scopes": [
    "string"
  ],
  "allowed_ips": [
    "203.0.113.10"
  ],
  "is_active": true,
  "expires_at": "2026-01-15T12:30:00.000Z",
  "last_used_at": "2026-01-15T12:30:00.000Z",
  "created_at": "2026-01-15T12:30:00.000Z",
  "key_hash": "sk_live_mer_7d21"
}

POST`/api/v1/org/api-keys/:id/revoke`

Org

Auth: Dashboard session (JWT bearer). Se requiere membresía de la Organization.

Revoca una clave de API (la desactiva).

Parámetros de ruta

Campo	Tipo	Obligatorio	Descripción
`id`	string	Sí	API Key ID

Ejemplo de solicitud

curl -X POST https://api.tokeflow.com/api/v1/org/api-keys/obj_1a2b3c4d/revoke \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-organization-id: org_4b21e7c3"

Ejemplo de respuesta — 200

{
  "id": "obj_1a2b3c4d",
  "entity_type": "standard",
  "entity_id": "string",
  "name": "Acme Store",
  "key_prefix": "sk_live_mer_7d21",
  "scopes": [
    "string"
  ],
  "allowed_ips": [
    "203.0.113.10"
  ],
  "is_active": true,
  "expires_at": "2026-01-15T12:30:00.000Z",
  "last_used_at": "2026-01-15T12:30:00.000Z",
  "created_at": "2026-01-15T12:30:00.000Z",
  "key_hash": "sk_live_mer_7d21"
}

Errores

Los errores usan el envoltorio estándar. Los casos más comunes aquí:

HTTP	Significado
`400`	Parámetros inválidos o un estado que no permite esta operación.
`401`	Token de sesión del Dashboard ausente, expirado o inválido.
`403`	Autenticado, pero el usuario que inició sesión no tiene acceso a esta entidad.
`404`	El registro no existe o no es visible para esta entidad.

Claves de API de la Organization

El objeto de clave de API

Endpoints

GET`/api/v1/org/api-keys`

POST`/api/v1/org/api-keys`

GET`/api/v1/org/api-keys/scopes`

GET`/api/v1/org/api-keys/:id`

PATCH`/api/v1/org/api-keys/:id`

POST`/api/v1/org/api-keys/:id/revoke`

Errores

Relacionados

En esta página

Claves de API de la Organization

El objeto de clave de API

Endpoints

GET/api/v1/org/api-keys

POST/api/v1/org/api-keys

GET/api/v1/org/api-keys/scopes

GET/api/v1/org/api-keys/:id

PATCH/api/v1/org/api-keys/:id

POST/api/v1/org/api-keys/:id/revoke

Errores

Relacionados

En esta página

GET`/api/v1/org/api-keys`

POST`/api/v1/org/api-keys`

GET`/api/v1/org/api-keys/scopes`

GET`/api/v1/org/api-keys/:id`

PATCH`/api/v1/org/api-keys/:id`

POST`/api/v1/org/api-keys/:id/revoke`