> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://support.robaws.com/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# OAuth endpoints

This article describes the endpoints you need when building an integration with Robaws using the OAuth 2 standard. OAuth 2 is the required authentication method for [marketplace integrations](https://support.robaws.com/nl/article/robaws-api-kue9an/); for a custom one-customer integration, HTTP Basic Authentication is usually the better fit.

## Before you start

Register your integration to obtain a **client id** and **client secret**. At the moment this is only possible by e-mail to support@robaws.com. Please include:

* the scopes your integration needs;
* the redirect URL(s) we should allow for your client.

A redirect URL that is not registered for your client is rejected with an HTTP 400.

## Scopes

The following scopes are available:

* settings
* clients
* work-orders
* planning-items
* employees
* materials
* installations
* profile
* projects
* articles
* posts
* sales-orders
* stock-changes
* offers
* users
* suppliers
* sales-invoices
* purchase-invoices
* time-registrations
* scheduled-maintenances

Separate multiple scopes with a space. A scope that is not on your client's allow-list is rejected at authorize time.

## Authorize endpoint

Request method: GET
URL: `https://app.robaws.com/oauth2/authorize`

**Required query parameters:**

* `client_id`
* `redirect_uri`

**Optional query parameters:**

* `response_type` (default = `code`)
* `scope`
* `state` (max 10 000 characters)

Only `response_type=code` is supported; any other value returns HTTP 400.

This is an interactive, browser-based step. The user logs in to Robaws, picks a tenant if the account has access to more than one, and — depending on your client configuration — confirms a consent screen. After that, Robaws redirects to your `redirect_uri` with the authorization code (and your `state`, if you supplied one).

## Tokens endpoint (authorization code flow)

For exchanging an authorization code for an access and refresh token.

Request method: POST
URL: `https://app.robaws.com/oauth2/tokens`
Content-Type: `application/x-www-form-urlencoded`

**Required body parameters:**

* `grant_type` (`authorization_code`)
* `client_id`
* `client_secret`
* `code`
* `redirect_uri`

## Tokens endpoint (refresh)

For exchanging a refresh token for a new access token.

Request method: POST
URL: `https://app.robaws.com/oauth2/tokens`
Content-Type: `application/x-www-form-urlencoded`

**Required body parameters:**

* `grant_type` (`refresh_token`)
* `client_id`
* `client_secret`
* `refresh_token`

## Token response

Both grants return the same JSON body:

```
{
    "access_token": "at.v2...",
    "refresh_token": "rt.v2...",
    "expires_in": 3600,
    "token_type": "Bearer"
}
```

Use the access token as a bearer token against the [Robaws API](https://support.robaws.com/nl/article/robaws-api-kue9an/):

```
GET https://app.robaws.com/api/v2/offers
Authorization: Bearer at.v2...
```

## Token lifetimes

| Token | Lifetime |
| ---- |
| Authorization code | 60 seconds, single use |
| Access token | 3600 seconds (1 hour) by default |
| Refresh token | 60 days |

Refresh tokens are **not** rotated: a refresh call returns a new access token but keeps the same refresh token, valid until its own expiry. Do not refresh access tokens until they are (almost) expired.

`client_secret` is only enforced for confidential clients. If your client was registered without a secret (a public client), you can omit it.