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

# Início rápido

> Crie uma conta, gere credenciais de API e faça sua primeira solicitação autenticada.

Este guia leva você do início até uma chamada autenticada à API. O processo deve levar poucos minutos.

<a id="prerequisites" />

## Pré-requisitos

* Um endereço de e-mail para verificar a conta.
* `curl` e `jq` para o exemplo com token bearer abaixo.

<a id="create-an-account" />

## Crie uma conta

<Steps>
  <Step title="Cadastre-se">
    Cadastre-se em [console.basaltic.sh](https://console.basaltic.sh/auth/signup).

    O cadastro, a verificação de e-mail e a configuração de faturamento são feitos pelo console e não fazem parte da API pública.
  </Step>

  <Step title="Verifique seu e-mail">
    O cadastro envia um código de seis dígitos. A conta só pode criar recursos depois da verificação.
  </Step>
</Steps>

<a id="issue-api-credentials" />

## Gere credenciais de API

Seu login no console identifica você como uma pessoa. O acesso programático usa uma **conta de serviço** e sua chave de acesso. Crie uma no console em **Identity & access** → **Service accounts**, ou pela API:

<Steps>
  <Step title="Crie a conta de serviço">
    ```bash theme={null}
    POST https://iam.basaltic.sh/v1/service-accounts
    {"name": "deploy-bot"}
    ```

    Uma conta de serviço pertence à conta selecionada e começa sem permissões. Associe uma política da conta que permita as ações necessárias. Para a solicitação abaixo, permita `compute:ListInstances`. Contas de serviço não podem participar de grupos. O acesso à organização usa uma concessão separada de política da organização.
  </Step>

  <Step title="Crie uma credencial para ela">
    ```bash theme={null}
    POST https://iam.basaltic.sh/v1/service-accounts/{service_account_id}/credentials
    {"name": "production-key"}
    ```

    A resposta contém a credencial e seu segredo:

    ```json theme={null}
    {
      "credential": {
        "id": "3f8a1c2d-4b5e-6789-abcd-ef0123456789",
        "name": "production-key",
        "access_key_id": "BYCLD550E8400E29B41D4",
        "created_at": "2026-01-15T09:30:00Z"
      },
      "secret_access_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
    }
    ```

    <Warning>
      `secret_access_key` é retornado **uma única vez**, na criação. Ele não é armazenado em um formato que a API possa exibir novamente. Se você o perder, exclua a credencial e crie outra.
    </Warning>
  </Step>
</Steps>

<a id="make-a-request" />

## Faça uma solicitação

Obtenha um token e envie-o como credencial bearer. Esse é o fluxo completo.

```bash theme={null}
TOKEN=$(curl -s -u "$ACCESS_KEY_ID:$SECRET_ACCESS_KEY" \
  -d grant_type=client_credentials \
  https://iam.basaltic.sh/v1/oauth/token | jq -r .access_token)

curl -s -H "Authorization: Bearer $TOKEN" \
     -H "X-Account-Id: $ACCOUNT_ID" \
  https://compute.sa-saopaulo-1.basaltic.sh/v1/instances
```

Uma conta nova não tem instâncias. Portanto, uma resposta `200` com uma lista vazia indica que a chamada foi bem-sucedida.

Esse é o fluxo padrão de credenciais do cliente do OAuth 2.0. Qualquer biblioteca HTTP compatível com OAuth pode executá-lo e renovar o token automaticamente. Seu par de chaves de acesso fornece o identificador e o segredo do cliente.

<Tip>
  Os tokens duram uma hora por padrão. Solicite outra duração com `duration_seconds`, entre 900 e 43200. Valores fora desse intervalo são ajustados aos limites, em vez de recusados.
</Tip>

<Warning>
  Duas recusas são parecidas, mas exigem soluções diferentes. `invalid_client` indica que a chave foi rejeitada: verifique-a ou faça sua rotação. `invalid_grant` indica que a chave está correta e que sua organização está suspensa ou ainda em integração. Nesse caso, trocar uma chave funcional apenas faria você perder tempo.
</Warning>

<a id="object-storage-uses-the-same-key-pair" />

## O armazenamento de objetos usa o mesmo par de chaves

O endpoint compatível com S3 verifica o AWS Signature Version 4, usado por todos os clientes S3. Configure um cliente para acessar o endpoint com o **mesmo par de chaves de acesso**, sem token:

```bash theme={null}
aws --endpoint-url https://objects.sa-saopaulo-1.basaltic.cloud \
  s3 ls
```

Uma credencial atende aos dois casos: um token bearer para esta API e o próprio par de chaves para S3. Você não precisa escolher um modo de autenticação ao fazer a solicitação.

<a id="where-to-go-next" />

## Próximos passos

<CardGroup cols={2}>
  <Card title="Autenticação" icon="key" href="/pt/authentication">
    Troca de tokens bearer, login pessoal e credenciais temporárias de funções.
  </Card>

  <Card title="Regiões e endpoints" icon="globe" href="/pt/regions">
    Em qual host cada serviço responde.
  </Card>

  <Card title="Referência da API" icon="code" href="/pt/api-reference/introduction">
    Todas as operações e seus esquemas.
  </Card>

  <Card title="Suporte" icon="life-ring" href="/pt/support">
    Quando algo não funciona e você precisa falar com alguém.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.