> ## Documentation Index
> Fetch the complete documentation index at: https://developers.portao3.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Make your first authenticated call to the Portão 3 API

This guide takes you from credentials to your first successful API call.

## Prerequisites

* A Portão 3 account. Your account manager provides either **user credentials** (email and password) or **API client credentials** (`client_id` / `client_secret`) for server-to-server integrations.
* Your `realmId` and `organizationId`, shared during onboarding. Tenant-scoped endpoints require both in the path.

## Step 1: Get an access token

Authenticate against the Identity service. Both flows use the same endpoint and return the same token payload.

<Tabs>
  <Tab title="User credentials">
    ```bash theme={null}
    curl -X POST https://api.identity.v2.portao3.com.br/auth/sign-in \
      -H "Content-Type: application/json" \
      -d '{
        "email": "you@yourcompany.com.br",
        "password": "your-password"
      }'
    ```
  </Tab>

  <Tab title="API client (server-to-server)">
    Send your `client_id` and `client_secret` as HTTP Basic credentials and set `grantType` in the body:

    ```bash theme={null}
    # base64-encode the credentials; tr -d '\n' strips any line wrapping GNU base64 adds
    BASIC_AUTH=$(printf '%s' "$CLIENT_ID:$CLIENT_SECRET" | base64 | tr -d '\n')

    curl -X POST https://api.identity.v2.portao3.com.br/auth/sign-in \
      -H "Authorization: Basic $BASIC_AUTH" \
      -H "Content-Type: application/json" \
      -d '{ "grantType": "client_credentials" }'
    ```
  </Tab>
</Tabs>

A successful sign-in returns your tokens:

```json theme={null}
{
  "accessToken": "eyJraWQiOi...",
  "idToken": "eyJraWQiOi...",
  "refreshToken": "eyJjdHkiOi..."
}
```

Use the `accessToken` as your bearer token on every API request.

<Note>
  If your user has **MFA enabled**, the response contains a `challenge` and a `session` instead of tokens. Complete the sign-in with `POST /auth/confirm-mfa`, sending your `email`, the one-time `userCode` from your authenticator app, and the `session` value returned by sign-in. The response contains your tokens.
</Note>

## Step 2: Make your first call

Verify the token by fetching the authenticated user's profile:

```bash theme={null}
curl https://api.identity.v2.portao3.com.br/me \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

A `200` response confirms your token works.

## Step 3: Call a tenant-scoped endpoint

Most endpoints are scoped to your realm and organization. For example, list your billing contracts:

```bash theme={null}
curl "https://api.billing.v2.portao3.com.br/realms/$REALM_ID/organizations/$ORG_ID/contracts" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

If you get a `403`, check that the `realmId` and `organizationId` in the path match the tenant your credentials belong to.

## Step 4: Refresh your token

Access tokens are short-lived. When one expires, exchange your refresh token for new tokens instead of signing in again:

```bash theme={null}
curl -X POST https://api.identity.v2.portao3.com.br/auth/refresh-token \
  -H "Content-Type: application/json" \
  -d '{
    "accessToken": "<expired-access-token>",
    "refreshToken": "<your-refresh-token>"
  }'
```

You can also include your `idToken` in the body to refresh it at the same time.

## Next steps

<Columns cols={2}>
  <Card title="Browse the API Reference" icon="code" href="/api-reference/overview">
    Every endpoint across all Portão 3 services, with schemas and examples.
  </Card>

  <Card title="Get support" icon="life-ring" href="mailto:suporte@portao3.com.br">
    Questions about credentials, tenancy, or a specific endpoint? We can help.
  </Card>
</Columns>

<Tip>
  Stuck? Email [suporte@portao3.com.br](mailto:suporte@portao3.com.br) and include the `traceId` from any error response.
</Tip>