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

# Contas

> Gerenciar contas de médicos na sua instituição (somente chaves API institucionais)

<Note>
  O gerenciamento de contas só está disponível com uma **chave API institucional**. Chaves API de nível médico não têm acesso a esses endpoints.
</Note>

Chaves API institucionais podem criar e recuperar contas de médicos dentro da sua organização. Cada conta representa um médico que pode usar o scribe da Telepatia através da sua integração. Criar uma conta gera **duas** chaves pra essa conta — uma chave **secreta** (`sk_…`) para as chamadas de API do lado do servidor e uma chave **publicável** (`pk_…`) para o embed de navegador (veja [Tipos de chave](/pt-BR/scribe-api/authentication#tipos-de-chave)). Você pode rotacionar a chave secreta depois.

## Criar uma conta

`POST /v1/institutional/accounts` exige `email` e `doctorSpecialties`. Opcionalmente, envie `apiKeyConfig.validForDays` (1–365) pra controlar por quanto tempo a chave API gerada permanece válida; omita pra usar o padrão de 365 dias (1 ano).

```bash theme={null}
curl -X POST https://scribe-api.telepatia.ai/v1/institutional/accounts \
  -H "Authorization: Bearer SUA_CHAVE_API_INSTITUCIONAL" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "dr.juan@clinica.com",
    "doctorSpecialties": ["cardiology"],
    "nameFull": "Dr. Juan Pérez",
    "internalCode": "DOC-001",
    "apiKeyConfig": { "validForDays": 365 }
  }'
```

**Resposta:**

```json theme={null}
{
  "id": "acc_a1b2c3d4e5f6g7h8",
  "email": "dr.juan@clinica.com",
  "apiKey": "<shown-once-store-securely>",
  "publishableApiKey": "<shown-once-store-securely>",
  "internalCode": "DOC-001",
  "expiresAt": "2027-06-17T00:00:00Z",
  "apiKeyExpiresInDays": 365
}
```

<Warning>
  `apiKey` (secreta) e `publishableApiKey` (publicável) são retornadas **apenas uma vez** — guarde-as com segurança. `expiresAt` é o timestamp UTC em que as chaves param de funcionar, e `apiKeyExpiresInDays` reflete a validade que foi aplicada. Use a chave secreta para as chamadas de API do lado do servidor; a chave publicável é para o embed de navegador e não pode chamar a API diretamente.
</Warning>

Guarde o `id` (ou o seu `internalCode`) — você pode usar qualquer um dos dois pra recuperar a conta depois.

## Recuperar uma conta

Busque uma conta pelo seu `id` (`acc_*`) ou pelo seu próprio `internalCode`.

```bash theme={null}
curl https://scribe-api.telepatia.ai/v1/institutional/accounts/acc_a1b2c3d4e5f6g7h8 \
  -H "Authorization: Bearer SUA_CHAVE_API_INSTITUCIONAL"
```

**Resposta:**

```json theme={null}
{
  "id": "acc_a1b2c3d4e5f6g7h8",
  "email": "dr.juan@clinica.com",
  "nameFull": "Dr. Juan Pérez",
  "doctorSpecialties": ["CARDIOLOGY"],
  "enabled": true,
  "internalCode": "DOC-001",
  "createdAt": "2024-01-15T10:30:00Z"
}
```

## Regenerar uma chave de API

Rotacione a chave API de uma conta com `POST /v1/institutional/accounts/{account_id}/api-keys/regenerate`, identificando a conta pelo seu `id` (`acc_*`) ou `internalCode`. Opcionalmente, envie `validForDays` (1–365) pra definir a validade da nova chave; omita pra manter o padrão da conta.

```bash theme={null}
curl -X POST https://scribe-api.telepatia.ai/v1/institutional/accounts/acc_a1b2c3d4e5f6g7h8/api-keys/regenerate \
  -H "Authorization: Bearer SUA_CHAVE_API_INSTITUCIONAL" \
  -H "Content-Type: application/json" \
  -d '{ "validForDays": 365 }'
```

**Resposta:**

```json theme={null}
{
  "accountId": "acc_a1b2c3d4e5f6g7h8",
  "apiKey": "<shown-once-store-securely>",
  "id": "ak_a1b2c3d4e5f6g7h8",
  "prefix": "sk_prod_a1b2c3d4...e5f6",
  "mode": "prod",
  "expiresAt": "2027-01-15T10:30:00Z"
}
```

<Warning>
  Regenerar revoga a chave anterior (após um breve período de carência) e retorna a nova `apiKey` sem criptografia **uma única vez** — atualize sua integração antes que o período de carência termine. A regeneração é limitada a **uma por conta a cada 2 minutos**; exceder esse limite retorna `429 rate_limit_exceeded`. Veja [Tratamento de erros](/pt-BR/scribe-api/errors#erros-de-chave-de-api).
</Warning>