> For the complete documentation index, see [llms.txt](https://docs.bullcredtech.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bullcredtech.com/api-reference/apis-en/guias/authentication.md).

# Authentication

The Bull API uses OAuth 2.0 Client Credentials Flow via AWS Cognito for authentication. All API requests must include a valid JWT token in the header `Authorization`.

## <mark style="color:$primary;">Get access token</mark>

Make a `POST` to the authentication endpoint with your credentials:

### <mark style="color:$primary;">Authentication endpoints</mark>

| ENVIRONMENT    | URL                                                      |
| -------------- | -------------------------------------------------------- |
| **Staging**    | `https://api-auth.staging.bullcredtech.com/oauth2/token` |
| **Production** | `https://api-auth.bullcredtech.com/oauth2/token`         |

### <mark style="color:$primary;">Request</mark>

```http
POST /oauth2/token HTTP/1.1
Host: api-auth.bullcredtech.com
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id={SEU_CLIENT_ID}&client_secret={SEU_CLIENT_SECRET}
```

### <mark style="color:$primary;">Parameters</mark>

| PARAMETER       | TYPE   | REQUIRED | DESCRIPTION                 |
| --------------- | ------ | :------: | --------------------------- |
| `grant_type`    | string |    Yes   | Fixed: `client_credentials` |
| `client_id`     | string |    Yes   | Provided by the Bull team   |
| `client_secret` | string |    Yes   | Provided by the Bull team   |

### <mark style="color:$primary;">Successful response (200 OK)</mark>

```json
{
  "access_token": "eyJraWQiOiJxYTZvVFFoaVR0OTN5cm14...",
  "expires_in": 3600,
  "token_type": "Bearer"
}
```

<table><thead><tr><th width="249">FIELD</th><th>TYPE</th><th>Description</th></tr></thead><tbody><tr><td><code>access_token</code></td><td>string</td><td>JWT token to authenticate requests</td></tr><tr><td><code>expires_in</code></td><td>number</td><td>Validity in seconds: <code>3600</code> = 1 hour</td></tr><tr><td><code>token_type</code></td><td>string</td><td>Always <code>Bearer</code></td></tr></tbody></table>

***

## <mark style="color:$primary;">Using the token</mark>

Include the token in the header `Authorization` of **all** API requests:

```http
Authorization: Bearer {access_token}
```

***

## <mark style="color:$primary;">Token Renewal</mark>

* **Renew before it expires** → Request a new token \~5 minutes before the `expires_in` to avoid interruptions
* **Store the token in memory and reuse it between requests** → Do not generate a new token for each call
* **Automatic retry on 401** → If the API returns `401 Unauthorized`, get a new token and repeat the request automatically
* **Environment variables** → Never put credentials in the code. Use `process.env`, `os.environ` or a secret manager

***

## <mark style="color:$primary;">Full example</mark>

```bash
# 1. Get token
TOKEN_RESPONSE=$(curl -s -X POST \\
  https://api-auth.staging.bullcredtech.com/oauth2/token \\
  -H "Content-Type: application/x-www-form-urlencoded" \\
  -d "grant_type=client_credentials\\
&client_id=SEU_CLIENT_ID\\
&client_secret=SEU_CLIENT_SECRET")

ACCESS_TOKEN=$(echo $TOKEN_RESPONSE | jq -r '.access_token')

# 2. Use token to create proposal
curl -X POST https://api.staging.bullcredtech.com/proposals/start \\
  -H "Content-Type: application/json" \\
  -H "Authorization: Bearer $ACCESS_TOKEN" \\
  -d '{
    "cpf": "12345678901",
    "full_name": "João da Silva",
    "birth_date": "1985-03-15"
  }'
```

***

## <mark style="color:$primary;">Security</mark>

{% hint style="danger" %}
**NEVER DO THIS**

* Expose `client_secret`in frontend code
* Commit credentials to the repository
* Share production credentials
* Use staging credentials in production
  {% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.bullcredtech.com/api-reference/apis-en/guias/authentication.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.