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

# Token authentication

> Issue and refresh a bearer access token using OAuth-style grants.

> [!WARNING]
>
> This is a different contract from [Authentication](https://sage.ask-wire.com/api-reference/endpoint/authentication.md),
> which is the confirmed, live login flow. The flow below has not been
> verified against a live deployment — treat it as a candidate alternative,
> not something to integrate against yet.

## Overview

Obtain a bearer token with a username and password, then send it as `Authorization: Bearer <token>` on every subsequent request. Rotate tokens with the refresh grant rather than re-sending credentials.

***

## Issue a token

`POST /auth/token`

### Body (application/json)

| Field | Type | Required | Description |
| - | - | - | - |
| `grant_type` | string | Yes | `password`. |
| `username` | string | Yes | Account username. |
| `password` | string | Yes | Account password. |

### Response `200`

| Field | Type | Description |
| - | - | - |
| `access_token` | string | Bearer token to use on subsequent requests. |
| `token_type` | string | `Bearer`. |
| `expires_in` | integer | Token lifetime in seconds. |
| `refresh_token` | string | Use with the refresh grant to rotate the token. |
| `scope` | string | Space-separated granted scopes. |

***

## Refresh a token

`POST /auth/refresh`

### Body (application/json)

| Field | Type | Required | Description |
| - | - | - | - |
| `grant_type` | string | Yes | `refresh_token`. |
| `refresh_token` | string | Yes | The refresh token to redeem. |

### Response `200`

Same shape as [Issue a token](#issue-a-token).

***

## Example

```json theme={null}
{
  "grant_type": "password",
  "username": "client_user",
  "password": "your_password"
}
```

```json theme={null}
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "def50200c8a1...",
  "scope": "reconstruction environmental"
}
```


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