Conceitos principais
Os objetos com que você trabalha no Authio — contas, realms, clients, usuários, papéis, escopos, consumers, organizações, servidores de recurso e sessões — e como eles se encaixam.
Tudo o que você configura no Authio se apoia em um conjunto pequeno de objetos. A sua conta é dona de um ou mais realms. Cada realm é um provedor de identidade independente, com usuários, aplicações e chaves próprios. Dentro de um realm, os clients fazem o login das pessoas e pedem tokens, e os servidores de recurso são as APIs a que esses tokens se destinam.
Esta página explica cada objeto em poucos parágrafos e aponta para a página que o detalha. Se você ainda não criou nada, o Início rápido acompanha a criação do seu primeiro realm e client.
Como eles se relacionam
Conta
├── Equipe: dono, administradores, desenvolvedores, auditores
├── Segredos de API
├── Papéis e escopos
└── Realm acme (emissor https://authio.api.hyperio.tech/realms/acme)
├── Usuários
├── Organizações
├── Servidores de recurso
└── Client acme-web
├── Consumers
└── Grupos| Objeto | Pertence a | Para que serve |
|---|---|---|
| Conta | — | A sua empresa no Authio: a assinatura, a equipe que opera o console e tudo o que está abaixo. |
| Realm | Conta | Um tenant isolado, com emissor, chaves, usuários, clients e políticas próprios. |
| Client | Realm | Uma aplicação que faz o login de pessoas ou pede tokens. |
| Usuário | Realm | Uma pessoa que faz login. Um usuário por pessoa em cada realm. |
| Consumer | Client | Uma identidade de máquina com credencial, escopos e papéis próprios. |
| Papel | Conta, opcionalmente restrito a um realm, client, usuário ou grupo | Um conjunto nomeado de claims levado nos tokens de quem o detém. |
| Escopo | Conta, opcionalmente restrito a um realm ou client | O nome de uma permissão que uma aplicação pede. |
| Organização | Realm | Um dos seus clientes corporativos, com membros e domínios próprios. |
| Servidor de recurso | Realm | Uma API ou servidor MCP para o qual os tokens são emitidos. |
| Sessão | Usuário e client | O registro de um login, citado por todo token emitido a partir dele. |
Conta
A conta é a sua empresa no Authio. Ela guarda a assinatura, a equipe que entra no console, os segredos de API que a sua automação usa, os papéis e escopos que você define e todos os realms que você cria. Os registros pertencem à conta, e não à pessoa que os criou, então nada se perde quando alguém sai da equipe.
Cada membro da equipe tem um de quatro papéis da conta — Dono, Administrador, Desenvolvedor ou Auditor — que decidem o que ele vê e altera. Equipe e acesso cobre os papéis e os convites, e Planos e cobrança cobre a assinatura.
Realm
Um realm é um tenant isolado e um provedor de identidade completo. Ele tem emissor, documento de discovery e chaves públicas próprios, usuários, clients e sessões próprios, e a sua própria política de senha e de bloqueio. Um token emitido em um realm nunca é aceito em outro, o que faz do realm a fronteira certa entre ambientes, como produção e homologação, ou entre produtos que não podem compartilhar usuários.
O ID do realm faz parte de todos os endereços que o realm publica. Ele tem de 3 a 64 caracteres entre letras minúsculas, dígitos e hífens, é único em todo o Authio e não pode ser trocado depois que o realm existe.
Emissor https://authio.api.hyperio.tech/realms/acme
Discovery https://authio.api.hyperio.tech/realms/acme/.well-known/openid-configuration
JWKS https://authio.api.hyperio.tech/realms/acme/protocol/openid-connect/certsAs chaves de assinatura são geradas por client e publicadas juntas no JWKS do realm, então uma API confere qualquer token do realm contra um único conjunto de chaves. As chaves giram automaticamente, a cada 90 dias por padrão, e uma chave substituída continua publicada até expirar o último token que ela assinou. Você acompanha e gira as chaves em Chaves de assinatura.
Client
Um client é uma aplicação registrada em um realm: uma aplicação web, uma SPA, um app mobile ou desktop, uma CLI, um serviço de back-end ou um agente de IA. O client ID — letras minúsculas, dígitos e hífens, com até 100 caracteres — é o que a aplicação envia ao Authio, e o nome de exibição é o que as pessoas veem na tela de login.
| Tipo | Segredo | Autenticação no endpoint de token | Uso típico |
|---|---|---|---|
| Confidencial | Sim, gerado pelo Authio e mostrado só na criação ou na rotação | client_secret_basic (padrão) ou client_secret_post | Aplicações web renderizadas no servidor, back-ends e serviços |
| Público | Não | none, com PKCE em S256 obrigatório | SPAs, apps mobile e desktop, CLIs |
Cada client também decide, independentemente dos outros clients do mesmo realm:
- Os redirect URIs: os únicos endereços para onde o Authio devolve a pessoa depois do login, comparados por inteiro.
- Os grant types: as formas pelas quais ele pode pedir um token. O PKCE é exigido por padrão no fluxo authorization code.
- Os passos de login: senha, código de uso único, passkey ou aprovação por push, e se cada um é obrigatório.
- Quem pode entrar: por padrão, só usuários vinculados ao client, como os criados por ele ou os que receberam acesso. Desligar essa opção deixa entrar qualquer usuário do realm.
- As configurações de token: tempos de vida, formato, algoritmo de assinatura e a frequência de rotação das chaves.
O Authio oferece sete grant types, cada um ligado por client:
| Grant | grant_type | Usado para |
|---|---|---|
| Authorization code | authorization_code | Aplicações que fazem o login de uma pessoa pelo navegador |
| Refresh token | refresh_token | Renovar tokens sem um novo login |
| Client credentials | client_credentials | Serviços que chamam APIs em nome próprio |
| Device code | urn:ietf:params:oauth:grant-type:device_code | TVs, CLIs e dispositivos sem navegador |
| Token exchange | urn:ietf:params:oauth:grant-type:token-exchange | Agir em nome de uma pessoa, e contas conectadas |
| Password | password | Integrações legadas que não conseguem abrir um navegador |
| Personal access token | personal_access_token | Scripts e pipelines com uma chave pré-gerada |
Usuário
Um usuário é uma pessoa que faz login em um realm. Cada pessoa tem um usuário por realm — um nome de usuário, uma senha, um conjunto de passkeys e de segundos fatores — compartilhado por todos os clients daquele realm. A política de senha e de bloqueio do realm vale para todos eles, e cada client decide quais passos de login pedir.
Os usuários são criados por um administrador em Usuários ou pela API administrativa, no primeiro login por um provedor de identidade externo, ou importados de outro provedor. Usuários de realms diferentes não têm relação entre si, mesmo quando compartilham um endereço de e-mail.
Usuários do console e usuários do realm
As pessoas da sua equipe também são usuários, mas de outro realm: o console faz login pelo login hospedado do realm do próprio Authio, como qualquer outra aplicação. Um usuário do console nunca é usuário dos seus realms, então entrar no console como ana@acme.com e entrar na sua aplicação como ana@acme.com são dois usuários diferentes, com credenciais diferentes. Cada usuário do console pertence a no máximo uma conta do Authio.
Papéis e escopos
Um papel diz o que alguém é. É um conjunto nomeado de claims, definido na sua conta, que o Authio grava nos tokens de quem o detém. Um papel chega a um usuário de quatro formas: atribuído diretamente, por um grupo de que ele faz parte, concedido por um client a todos que entram por ele ou concedido por um realm a todos que estão nele. Consumers também têm papéis.
Um escopo diz o que uma aplicação pode pedir. Os clients pedem escopos no login, tanto os do OpenID Connect, como openid, profile, email e offline_access, quanto os seus, como orders:read. Para cada client, um escopo é padrão, sempre concedido, ou opcional, concedido quando o client o pede. Os papéis do usuário aparecem no access token quando o escopo roles é concedido.
Um papel ou um escopo pode ser global na conta ou exclusivo de um realm ou client (um papel também de um usuário ou grupo), o que limita onde ele pode ser atribuído. Um grupo é um conjunto nomeado de usuários de um client que repassa os seus papéis a todos os membros. Papéis e permissões e Escopos e claims detalham os dois.
Consumers
Um consumer é uma identidade de máquina ligada a um client: um serviço de back-end, a integração de um parceiro ou uma rotina agendada que se autentica em nome próprio, e não em nome de uma pessoa. Cada consumer tem a sua credencial — um segredo para o grant client credentials, uma chave de API ou um personal access token — e os seus próprios escopos e papéis.
Um client que atende várias integrações dá a cada uma o seu consumer, em vez de dividir um único segredo entre elas, de modo que uma integração pode ser suspensa ou ter a credencial trocada sem afetar as outras. No console, eles aparecem em Consumidores. Veja Máquina a máquina.
Organizações
Uma organização é um dos seus clientes corporativos, representado dentro de um realm. Ela tem membros próprios, domínios de e-mail comprovados por um registro DNS TXT, provedores de identidade e a marca da tela de login, de modo que um produto B2B atende todos os clientes a partir de um realm, em vez de criar um realm para cada um.
Uma aplicação pede o login de uma organização enviando o alias dela no parâmetro organization do pedido de autorização, e os tokens levam a organização em que a pessoa entrou como org_id e org_alias. Ser membro não concede papéis por si só: os papéis continuam vindo de atribuições, grupos e concessões. Veja Organizações.
Servidores de recurso
Um servidor de recurso é uma API, muitas vezes um servidor MCP, registrada em um realm. O seu identificador é uma URI absoluta que vira a audiência (aud) dos tokens emitidos para ele, de modo que a API pode recusar tokens destinados a qualquer outro lugar. Ele declara os seus próprios escopos, lista os clients autorizados a pedir tokens para ele e indica um client confidencial que usa para fazer a introspecção desses tokens.
Um client pede um token para um servidor de recurso enviando o identificador dele no parâmetro resource (RFC 8707). Os servidores de recurso fazem parte da capacidade de integração MCP do seu plano. Veja Servidores de recurso.
Sessões
Fazer login abre uma sessão daquela pessoa naquele client, e todo token emitido a partir dela leva o ID da sessão na claim sid. Encerrar a sessão — a pessoa sai, um administrador a revoga ou o usuário é suspenso — impede que esses tokens sejam renovados e faz a introspecção informá-los como inativos. Uma sessão dura 10 horas por padrão, valor configurável por client.
O single sign-on é opcional por client e vem desligado. Os clients que participam compartilham o login do realm: quem entrou em um deles entra nos outros sem digitar credenciais de novo, desde que nada tenha mudado. Uma senha nova, uma suspensão ou um passo de login que o próximo client exige levam a pessoa de volta à tela de login. Veja Sessões e single sign-on.