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

# Authentication

> Use the authentication method and permissions assigned to your Nimbo integration.

Authentication depends on the API surface you use. Confirm the credentials and permissions for your integration with Nimbo; there is no universal credential documented here that grants access to every endpoint.

## Bearer authentication

For operations that use HTTP bearer authentication, send the integration token in the request header:

```http theme={null}
Authorization: Bearer <YOUR_INTEGRATION_TOKEN>
```

Replace the placeholder in your own secure environment. Keep integration credentials on your server and out of source control, browser code, and logs. Prefer headers for tokens; the documented CFDI download endpoints are a specific [query-token exception](/guides/billing).

## Choose an integration account

Use an account assigned to the integration and confirm its organization, permissions, and licensing with your administrator and Nimbo. Grant only the access the workflow needs.

The password grant below expects a Nimbo account password. A Google sign-in session or Google access token cannot replace that password in this request. If the account uses Google sign-in or two-factor authentication, confirm the supported setup with Nimbo before changing its sign-in settings.

## Obtain an integration token

For integrations approved to use an account's password grant, send the account email as `username` to [`POST /oauth/token`](/api-reference/authentication/post-oauthtoken). These examples use the [quickstart](/quickstart) base URL, including `/api/v1`. Load `NIMBO_USERNAME` and `NIMBO_PASSWORD` from your secure environment.

```bash theme={null}
curl --request POST "$NIMBO_API_BASE_URL/oauth/token" \
  --form-string "grant_type=password" \
  --form-string "username=$NIMBO_USERNAME" \
  --form-string "password=$NIMBO_PASSWORD"
```

A successful token response includes `access_token`, `token_type`, `expires_in`, `refresh_token`, and `created_at`. Use the returned expiry rather than hard-coding a token lifetime. Store and reuse the token instead of requesting a new one for every API call.

Accounts with two-factor authentication can receive a `403` response with `token_type: "2fa"` instead of an access token. Confirm the supported authentication flow with Nimbo for those accounts; repeating the password request does not complete verification.

## Refresh an integration token

When a refresh token was issued, exchange it at the same endpoint. Load `NIMBO_REFRESH_TOKEN` securely from the earlier response.

```bash theme={null}
curl --request POST "$NIMBO_API_BASE_URL/oauth/token" \
  --header "Content-Type: application/json" \
  --data "{\"grant_type\":\"refresh_token\",\"refresh_token\":\"$NIMBO_REFRESH_TOKEN\"}"
```

Store the returned token values securely and update your stored expiry. If refreshing fails, stop automatic retries and resolve the account or credential issue. Do not automatically replay a record-creation request unless you know it did not succeed.

## Patient portal tokens

Patient portal access uses phone verification through `/patient_portal/auth` and `/patient_portal/validate`. The validation response contains `token`, not the integration OAuth response's `access_token`. Use it only for the patient portal and the people authorized by that session. Follow the [patient portal workflow](/guides/patient-portal).

## Public reads

Some catalog and site operations accept requests without authentication. Check the security and parameter requirements for each operation. Access to a public read endpoint does not grant access to protected resources.

## Authentication errors

Use the error responses documented for your operation. If authentication fails, check the selected environment, credential validity, and assigned permissions before retrying. Do not substitute a patient-portal token for an integration credential. See [Troubleshooting](/guides/troubleshooting) for token, permission, and connection failures.