Quickstart

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.

User credentials
API client (server-to-server)

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"
  }'

Send your client_id and client_secret as HTTP Basic credentials and set grantType in the body:

# 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" }'

A successful sign-in returns your tokens:

{
  "accessToken": "eyJraWQiOi...",
  "idToken": "eyJraWQiOi...",
  "refreshToken": "eyJjdHkiOi..."
}

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

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.

Step 2: Make your first call

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

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:

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:

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

Browse the API Reference

Every endpoint across all Portão 3 services, with schemas and examples.

Get support

Questions about credentials, tenancy, or a specific endpoint? We can help.

Stuck? Email suporte@portao3.com.br and include the traceId from any error response.

Getting Started

Integration guides

Cards

PIX & payments

Accounts & wallets

Building your integration

Prerequisites

Step 1: Get an access token

Step 2: Make your first call

Step 3: Call a tenant-scoped endpoint

Step 4: Refresh your token

Next steps

Browse the API Reference

Get support

​Prerequisites

​Step 1: Get an access token

​Step 2: Make your first call

​Step 3: Call a tenant-scoped endpoint

​Step 4: Refresh your token

​Next steps

Browse the API Reference

Get support

Prerequisites

Step 1: Get an access token

Step 2: Make your first call

Step 3: Call a tenant-scoped endpoint

Step 4: Refresh your token

Next steps