Organizações

No serviço hospedado, organizações, membros, chaves de API, créditos e licenças de implantação são gerenciados pela API de organizações em https://ephemer.al/v1. O portal do cliente e o painel a usam por você; esta página é para scripts e integrações.

Autenticação

Estes endpoints agem em nome de uma pessoa. Entre com POST /v1/auth/login e envie o token retornado como token bearer. As sessões duram 30 dias; POST /v1/auth/logout encerra uma antes do prazo.

Terminal

curl https://ephemer.al/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","password":"…"}'

A resposta é {"token": "...", "user": {...}, "organizations": [...]}. Cada organização tem id, name e a sua role. Tudo o que vem abaixo, exceto listar e criar organizações e aceitar um convite, exige a função de proprietário ou administrador na organização indicada no caminho.

As chaves de API são recusadas aqui

As chaves de API da organização, incluindo as de administrador, não podem chamar os endpoints de membros, chaves, faturamento ou licenças. Isso impede que uma chave vazada adicione pessoas, emita chaves ou gaste dinheiro. Elas podem ler o saldo da própria organização.

GET/v1/organizations

Lista as organizações às quais você pertence, cada uma com id, name e role.

POST/v1/organizations

Cria uma organização a partir de {"name": "..."} e faz de você o proprietário. Retorna 201 com {"id": "org_...", "name": "...", "role": "owner"}.

PATCH/v1/organizations/{id}

Proprietário ou administrador. Renomeia a organização com {"name": "..."}. O nome é aparado e deve ter de 1 a 200 caracteres. Retorna {"id": "org_...", "name": "...", "role": "owner"}. Membros recebem 403.

Membros

GET/v1/organizations/{id}/members

Lista os membros com id, email, name, role e avatar_url.

DELETE/v1/organizations/{id}/members/{user_id}

Remove um membro. Os administradores podem remover membros; somente o proprietário pode remover um administrador. O proprietário não pode ser removido.

PATCH/v1/organizations/{id}/members/{user_id}

Somente proprietário. Altera a função de um membro com {"role": "admin"} ou {"role": "member"}.

POST/v1/organizations/{id}/ownership

Somente proprietário. Transfere a propriedade a um membro existente com {"user_id": "..."}. Você passa a ser administrador.

Convites

POST/v1/organizations/{id}/invitations

Convida alguém com {"email": "...", "role": "member"}. role é admin ou member. Retorna 201 com token, url e email_delivery.

email_delivery é accepted quando o provedor de e-mail aceitou a mensagem, o que não garante que ela chegou à caixa de entrada. Se for unavailable ou failed, compartilhe a url retornada de forma privada. Os convites expiram após 7 dias. A pessoa convidada aceita com POST /v1/invitations/accept e {"token": "..."}, conectada com o endereço de e-mail convidado.

Chaves de API

GET/v1/organizations/{id}/keys

Lista as chaves com id, name, role e created_at. Os segredos nunca são listados.

POST/v1/organizations/{id}/keys

Cria uma chave a partir de {"name": "...", "role": "member"}. role é member ou admin e assume por padrão member.

201 Created

{
  "id": "key_0b7e4c2a9d1f8356e4a2c7b9d0f1e3a5",
  "name": "production-server",
  "role": "member",
  "key": "eak_…"
}

O valor de key é retornado apenas uma vez. Guarde-o antes de fechar a resposta.

DELETE/v1/organizations/{id}/keys/{key_id}

Revoga a chave imediatamente.

Perfil

Estes exigem uma sessão de usuário conectado; as chaves de API são recusadas. Os usuários, e cada entrada de membros, trazem avatar_url: um caminho como /v1/users/usr_…/avatar?v=3f2a…, ou null.

PUT/v1/me/avatar

A imagem bruta como corpo, com Content-Type image/png, image/jpeg ou image/webp, até 256 KiB. Retorna o mesmo corpo de GET /v1/auth/me. No máximo 20 envios por hora.

DELETE/v1/me/avatar

Remove a foto.

POST/v1/me/password

Altera a sua senha com {"current_password": "...", "new_password": "..."}. A nova senha tem de 12 a 72 bytes. As suas outras sessões são encerradas; a que fez a requisição continua conectada. No máximo 10 tentativas por hora.

GET/v1/users/{user_id}/avatar

A imagem, para esse usuário e para as pessoas que compartilham uma organização com ele; qualquer outra recebe 404. A URL muda quando a foto muda, então pode ser armazenada em cache indefinidamente.

Faturamento

Os valores nestes endpoints usam centavos para os montantes do Stripe e micros para os da carteira. Veja orçamentos e faturamento.

GET/v1/organizations/{id}/balance

Qualquer membro ou uma chave de API da organização. Retorna {"balance_micros": ..., "reserved_micros": ..., "available_micros": ...}: créditos mantidos, reservados para execuções não liquidadas e disponíveis para novas execuções. Compare available_micros com o orçamento de uma execução antes de iniciá-la.

GET/v1/organizations/{id}/billing

Retorna a carteira e as configurações de pagamento.

balance_micros, reserved_micros, available_microsinteger

Créditos mantidos, reservados para execuções não liquidadas e disponíveis para novas execuções.

ledgerarray

Os 100 lançamentos mais recentes, cada um com amount_micros, description, created_at e, quando se aplicam, run_id, payment_id e topup_id.

purchase_limitsobject

min_amount_cents, max_amount_cents e min_threshold_cents. Valide com base nestes valores em vez de fixar limites no código.

auto_topupobject

enabled, threshold_cents, amount_cents, payment_method_saved e last_topup_status.

payment_methodobject | null

O cartão usado nas recargas: brand, last4, exp_month, exp_year e source.

payment_method_syncstring

synced ou unavailable quando não foi possível acessar o Stripe. Uma consulta que falha não significa que não há cartão.

stripe_configuredboolean

Se os pagamentos estão disponíveis.

POST/v1/organizations/{id}/billing/checkout

Inicia uma compra de créditos com {"amount_cents": 2500} e retorna {"url": "..."} para o Stripe Checkout. Adicione "save_payment_method": true para salvar o cartão para recargas automáticas. Os valores vão de 500 a 1.000.000 de centavos.

POST/v1/organizations/{id}/billing/portal

Retorna {"url": "..."} para o portal do cliente do Stripe, onde os cartões são gerenciados.

PUT/v1/organizations/{id}/billing/auto-topup

Ativa a recarga automática com {"enabled": true, "threshold_cents": 1000, "amount_cents": 5000, "consent": true} ou a desativa com {"enabled": false}. Para ativar, é preciso ter um cartão salvo.

GET/v1/organizations/{id}/billing/payments

Histórico de pagamentos, dos mais recentes aos mais antigos. Aceita limit (de 1 a 100, padrão 25) e cursor e retorna {"payments": [...], "next_cursor": "..."}. Cada pagamento tem amount_cents, refunded_cents, disputed_cents, refund_status, created_at, topup_id e receipt_endpoint.

GET/v1/organizations/{id}/billing/payments/{payment_id}/receipt

Retorna {"url": "..."} para o recibo do Stripe, ou 404 se o Stripe não forneceu um.

Licenças de implantação

GET/v1/organizations/{id}/license

O direito de auto-hospedagem da organização, ou {"entitlement": null}.

GET/v1/organizations/{id}/deployments

Lista as instalações registradas.

POST/v1/organizations/{id}/deployments

Registra uma instalação com {"name": "..."} e retorna o token da licença uma única vez, com o ID de máquina gerado pelo Ephemeral (ou o machine_id que você enviar).

DELETE/v1/organizations/{id}/deployments/{deployment_id}

Desativa uma instalação.

As licenças de implantação descrevem estes campos e como as instalações usam o token.