Guides
  1. Getting Started

Authentication

Sign in with a form-encoded username and password, use the returned Bearer token on API requests, and refresh expired tokens.

Get an access token with your username and password, then use that token to authenticate all other API requests.

  1. Send a POST request to /auth/signin with your credentials in a form-encoded request body.
  2. Save the access_token from the response.
  3. 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 '[email protected]' \
  --data-urlencode 'password=your-password'

Request

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

[email protected]&password=some-secret-password

Response

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

If you sign in with a service account, 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.

triangle-exclamation

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.

triangle-exclamation

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.