tokeflow.com
DocumentaçãoReferência da APIDashboardsSDKsChangelog

Chaves de API da Organization

Gerencie chaves de API no nível da Organization a partir do Dashboard — crie, liste, inspecione escopos e revogue chaves que atuam em todos os Merchants da organização.

Esses endpoints alimentam a tela de chaves de API da Organization. Uma chave da Organization (sk_live_org_… / pk_live_org_…) pode atuar em todos os Merchants da organização, indicando o Merchant de destino com merchant_id em cada chamada — diferentemente de uma chave de Merchant, que é restrita a um único.

O segredo completo é exibido apenas na criação; depois disso, uma chave é identificada pelo seu prefixo não secreto. A revogação é imediata e permanente.

Esses endpoints alimentam a interface do Tokeflow Dashboard no nível da Organization. Eles são autenticados por sessão (JWT bearer) — o token vem do login no Dashboard, não de uma chave de API sk_/pk_. As solicitações também carregam o header x-organization-id, e o usuário autenticado deve ser membro dessa Organization.

O objeto de chave de API

Retornado pelos endpoints de listagem e de recuperação desta página.

CampoTipoDescrição
idstringIdentificador único da chave de API.
entity_typestringTipo de entidade (organization ou merchant).
entity_idstringID da entidade.
namestringNome legível da chave de API.
key_prefixstringPrefixo da chave para identificação.
scopesarrayEscopos/permissões da chave de API.
allowed_ipsarray | nullEndereços IP permitidos.
is_activebooleanIndica se a chave de API está ativa.
expires_atstring | nullData de expiração. (ISO 8601 UTC).
last_used_atstring | nullÚltima vez em que a chave foi usada. (ISO 8601 UTC).
created_atstringCarimbo de data/hora de criação. (ISO 8601 UTC).
key_hashstring—

Endpoints

GET/api/v1/org/api-keys

Org

Auth: Dashboard session (JWT bearer). É necessário ser membro da Organization.

Lista as chaves de API do Merchant.

Parâmetros de consulta

CampoTipoObrigatórioDescrição
pagenumberNãoNúmero da página (indexado a partir de 1). Padrão 1, mín. 1.
limitnumberNãoNúmero de itens por página. Padrão 20, mín. 1, máx. 100.

Exemplo de solicitação

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"

Exemplo de resposta — 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). É necessário ser membro da Organization.

Cria uma nova chave de API para o Merchant.

Campos da solicitação

CampoTipoObrigatórioDescrição
entity_typestringNãoTipo de entidade à qual a chave de API pertence. Um dos valores organization, merchant.
entity_idstringNãoID da entidade (organization ou merchant).
namestringSimNome legível da chave de API.
scopesarraySim—
allowed_ipsarraySim—
expires_atstringNãoData de expiração da chave de API (ISO 8601).
key_typestringNãoTipo de chave de API - secret ou public. Um dos valores secret, public.

Exemplo de solicitação

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"
  }'

Exemplo de resposta — 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). É necessário ser membro da Organization.

Retorna os escopos que podem ser atribuídos a chaves de API. Filtre por entity_type e/ou key_type.

Parâmetros de consulta

CampoTipoObrigatórioDescrição
entity_typestringSim—
key_typestringSim—

Exemplo de solicitação

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). É necessário ser membro da Organization.

Obtém uma chave de API por ID.

Parâmetros de caminho

CampoTipoObrigatórioDescrição
idstringSimAPI Key ID

Exemplo de solicitação

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

Exemplo de resposta — 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). É necessário ser membro da Organization.

Atualiza uma chave de API (ativa/desativa).

Parâmetros de caminho

CampoTipoObrigatórioDescrição
idstringSimAPI Key ID

Campos da solicitação

CampoTipoObrigatórioDescrição
is_activebooleanNãoIndica se a chave de API está ativa.

Exemplo de solicitação

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
  }'

Exemplo de resposta — 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). É necessário ser membro da Organization.

Revoga uma chave de API (desativa a chave).

Parâmetros de caminho

CampoTipoObrigatórioDescrição
idstringSimAPI Key ID

Exemplo de solicitação

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"

Exemplo de resposta — 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"
}

Erros

Os erros usam o envelope padrão. Os casos mais comuns aqui:

HTTPSignificado
400Parâmetros inválidos ou um estado que não permite esta operação.
401Token de sessão do Dashboard ausente, expirado ou inválido.
403Autenticado, mas o usuário autenticado não tem acesso a esta entidade.
404O registro não existe ou não é visível para esta entidade.

Relacionados

Visão geral do dashboard da Organization

Anterior

Trilha de auditoria da organização

Próxima

Nesta página

O objeto de chave de APIEndpointsGET /api/v1/org/api-keysPOST /api/v1/org/api-keysGET /api/v1/org/api-keys/scopesGET /api/v1/org/api-keys/:idPATCH /api/v1/org/api-keys/:idPOST /api/v1/org/api-keys/:id/revokeErrosRelacionados