API Changes from v1 to v2

A number of changes were made between AuthRocket 1 and AuthRocket 2. Many of these changes affect the APIs, which are outlined below.

New features and fields are not included here unless they replace something else removed from v1.

The path prefix for all API methods has changed from /v1 to /v2. The endpoint hostnames have also changed and are provided when generating a new API key.

Additionally, the text of several error messages has been updated.

Headers

AuthRocket-specific headers are no longer prefixed by x-.

In addition to AuthRocket-specific headers, authentication is now supported using an Authorization bearer token.

401 and 429 are no longer returned for user authentication failures (eg: bad password) or user-specific rate limits (eg: too many password attempts). Those errors are now returned as messages inside a normal 422 validation error.

For 429 errors, the rate limit headers are no longer prefixed by x-. Ratelimit-Reset now contains a standard HTTP date instead of a time_t epoch.

For 422 errors, errors is now a simple array of error messages instead of a hash/dict.

Core API

Credentials

Removed credential_type = api_key. (See related discussion under Users below.)

External auth providers

/authorize_url and /authorize_urls: url field renamed to auth_url.
/authorize and /authorize_token now return a Session.

Memberships

org_id is now required.
Permissions beginning with ar: are now reserved.

Sessions

Retrieving a session with a JWT token is no longer supported; extract and use the sid claim (session id; starts with kss_) instead.
Tokens are now OpenID Connect compatible.
- Renamed:
  - tk -> sid
  - uid -> sub
  - un -> preferred_username
  - fn -> given_name
  - ln -> family_name
  - n -> name
  - m -> orgs
  - m.p -> orgs.perm
  - m.o -> orgs.name
  - m.ocs -> orgs.cs
- Removed: m.cs
- Added: aud, email, email_verified, iss, locale, rid, orgs.mid, orgs.ref

Users

Users has been simplified to remove api type users. All users are now the equivalent of v1’s human type.

Removed user_type, api_key, /authenticate_key.
email is now required and must be unique across the realm.
username is now optional and some characters are no longer allowed.
/users/:id/authenticate signature changed to user: {password: ...}.
/users/:id/authenticate_code renamed to /users/authenticate_token and signature changed to user: {...}.
/users/:id/reset_password_with_token renamed to /users/reset_password_with_token.
/users/:id/verify_email renamed to /users/verify_email.
APIs that generate tokens no longer return partial user objects, just token.

Extended API (now Configuration API)

User management related APIs have been moved to the Core API. The rest of the Extended API has been renamed to the Configuration API.

Removed Signup Tokens (aka User Tokens).

LoginRocket API

LoginRocket 2 is significantly more capable than LoginRocket 1. As such, some features previously only available via the LR API are now also part of the LR 2 web UI, such as changing passwords. Additionally, LR 2 adds user profile management, multi-org (account) selection and management, and more.

LoginRocket API

Parameters and responses for many methods have been updated to match the underlying AR 2 API.

/check_session changed to GET /session.
/forgot_password renamed to /password/forgot.
/logout changed to DELETE /session.
/reset_password renamed to /password/reset.
/update_password renamed to /profile/password and now requires session.
/verify_email renamed to /email/verify.
/verify_login renamed to /login/verify.
Removed JSONP.

Javascript SDK

authrocket.js, the LR 1 SDK, has been replaced with loginrocket.js. It no longer requires jquery and is now available as an npm package (@authrocket/loginrocket).

Many request parameters and responses have been updated.
Functions no longer accept callbacks and now return promises instead.
Auto-redirects and response.url have been removed. If needed, build your own redirect URL using response.token.
checkSession renamed to getSession.
setInstanceUrl replaced with new LoginRocket({url: }).