Authentication

All Integrations API requests are authenticated with an OAuth 2.0 access token issued to a Service Road Atlas user. We support the Authorization Code grant with PKCE — suitable for mobile, desktop, and single-page apps.

Scopes

Scope	Grants
bulletins:read	Read road bulletins and conditions
bulletins:write	Post road bulletins on behalf of the user
profile:read	Read the signed-in user's profile

Only request the scopes your application actually needs — users see every scope on the consent screen.

Flow

1. Send the user to the authorization endpoint

https://backroadstatus.com/oauth2/authorize
    ?response_type=code
    &client_id=<your client id>
    &redirect_uri=<your registered redirect>
    &scope=bulletins:read%20bulletins:write
    &state=<random>
    &code_challenge=<PKCE challenge>
    &code_challenge_method=S256

The user signs in (if needed), reviews the scopes, and approves access. On approval we redirect to your redirect_uri with ?code=<auth code>&state=<state>.

2. Exchange the code for tokens

POST https://backroadstatus.com/oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=<auth code>
&redirect_uri=<your registered redirect>
&client_id=<your client id>
&code_verifier=<PKCE verifier>

The response contains access_token, refresh_token, expires_in, and scope.

3. Call the API

Send the access token as a bearer token:

GET /api/integrations/v1/me
Authorization: Bearer <access token>

4. Refresh when the token expires

Access tokens are valid for one hour. Use the refresh token to obtain a new access token:

POST https://backroadstatus.com/oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token=<refresh token>
&client_id=<your client id>

Refresh tokens are rotated on every use. The response contains a new access_token and a new refresh_token — discard the old one.