Authentication

Get an access token using a service account's your Unique Identifier and Password, then use that token to authenticate all other API requests.

Send a POST request to /auth/signin with your service account credentials in a form-encoded request body.
Save the access_token from the response.
Send the token in the Authorization header for all subsequent API requests.

Sign in

Send a POST request to /auth/signin with Content-Type: application/x-www-form-urlencoded.

curl https://bench.gobridgit.com/auth/signin \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'username=<SERVICE_ACCOUNT_UNIQUE_IDENTIFIER>' \
  --data-urlencode 'password=<SERVICE_ACCOUNT_PASSWORD>'

Request

POST /auth/signin HTTP/1.1
Content-Type: application/x-www-form-urlencoded

username=0123456789abcdef0123456789abcdef&password=Ex%25mple%5Bpass%5E7

Response

{
  "access_token": "...snip...",
  "token_type": "Bearer",
  "refresh_token": "...snip...",
  "expiry": "2020-01-01T00:00:00.413440849Z"
}

Only one active session can exist at a time. When you request a new token for that service account, the API invalidates the previous token. Concurrent sessions are not possible.

If multiple processes reuse the same service account, requesting a new token in one process can invalidate the token another process is still using and cause 401 Unauthorized responses.

Use the access token

Send the access_token as a Bearer token in the Authorization header.

Authorization: Bearer xxxYYYzzz

Use that header on all API requests after sign-in.

Optional: Refresh an expired token

When an access token expires, send the refresh_token to /auth/token to generate a new session.

Once you use a refresh token, the previous access token and refresh token are immediately invalidated.

curl https://bench.gobridgit.com/auth/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=refresh_token' \
  --data-urlencode 'refresh_token=your-refresh-token'

Request

POST /auth/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&refresh_token=tGzv3JOkF0XG5Qx2TlKWIA

Response

{
  "access_token": "...snip...",
  "token_type": "Bearer",
  "refresh_token": "...snip...",
  "expiry": "2020-01-01T00:00:00.413440849Z"
}

Troubleshooting

If sign-in fails, confirm you are sending the request to /auth/signin.
If the request is rejected, confirm the body is form-encoded and the Content-Type header is application/x-www-form-urlencoded.
If authenticated requests fail, confirm you are sending Authorization: Bearer <access_token>.
If a service account starts returning 401 Unauthorized after another sign-in, request a fresh token and confirm another process did not sign in with the same service account.
If refresh fails after a previous refresh succeeded, use the newest refresh_token, because older refresh tokens are invalidated after use.