Skip to main content

Authentication

Every API request is made on behalf of a RushHour user. The API checks that user's roles and permissions on each request, exactly as the Company Portal does, so an integration can never see or do more than the user it signs in as.

Today you authenticate by signing in with a user's email address and password. The API answers with a session token that you send with every following request.

Coming soon

A way for integrations to authenticate without a person's password is planned — see API tokens. It is not available yet, so use the sign-in flow on this page.

Choose the user to sign in as​

Create a dedicated Company Portal user for each integration rather than reusing a person's account:

  • Give it only the roles the integration needs — see Users, roles and permissions.
  • Sign in to the Company Portal with it once, so any first-time password setup is complete.
  • Prefer a user that belongs to a single company. A user who can switch between companies signs in to the company they last worked in.

Sign in​

POST /api/v1/Auth/Login
Content-Type: application/json
{
  "userName": "integration@example.com",
  "password": "the user's password"
}
FieldRequiredDescription
userNameYesThe email address the user signs in with.
passwordYesThe user's password.

A successful sign-in returns the token in data:

{
  "data": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…",
  "messages": [],
  "errors": [],
  "otherMessages": [],
  "success": true
}

A failed sign-in returns 400 Bad Request with success: false. The most common error codes are:

CodeMeaning
auth.invalid_loginThe email address or password is wrong, or the user is disabled.
auth.invalid_login_because_inactive_companyThe user's company is not active.

The API does not say whether it was the email address or the password that was wrong. If userName or password is missing or empty, you get the validation problem response described in API overview instead.

Send the token​

Put the token in the Authorization header of every request, after the word Bearer and a space:

curl "https://api.rushhourapp.com/api/v1/Permissions/CurrentRolesWithPermissions" \
  -H "Authorization: Bearer YOUR_TOKEN"

The request above is a good first check: it returns the roles of the signed-in user and the permissions each role grants in the current company.

For API requests, send the token only in the Authorization header. Never put a token in a URL.

What the token allows​

A session token acts as the user in the company they signed in to:

  • Permissions apply to every request. If the user's roles don't grant a permission an action needs, the API answers 403 Forbidden, usually with the code meta.missing_permission — see API overview.
  • Data is filtered the same way as in the portal. Lists only include what the user is allowed to see — for example, a user who may only view their own customers gets only those customers.
  • Actions are recorded under the user. Changes made through the API appear in activity logs and audit history under the integration user's name.

How long a token stays valid​

  • A session token is valid for up to 30 days from sign-in.
  • It stops working earlier if the user's password is changed or reset, or if the user is disabled or deleted. Requests then fail with 401 Unauthorized.
  • The API does not refresh session tokens. When a token expires or is rejected, sign in again to get a new one.

A simple approach for a long-running integration: keep the token in memory, and when a request returns 401, sign in once more and repeat the request. If signing in fails too, stop and alert someone rather than retrying in a loop.

Keep credentials safe​

  • Store the integration user's password in a secrets manager or your platform's secure configuration, never in source code.
  • Treat a session token like a password: anyone who has it can act as that user until it expires.
  • If a password or token may have leaked, reset or set a new password for the user in Settings → Users. That stops every session token already issued to the user.

Customer Portal and driver accounts​

The steps on this page are for Company Portal users. Customer Portal logins and driver accounts belong to the Customer Portal and the driver app — don't use them for integrations.

Last updated on