AuthRocket/PHP

The authrocket PHP package covers all of our Core API. It also covers select portions of the Configuration API.

For our Getting Started guide, see Integration with PHP.

Installation

The library is designed to be installed using composer. It should also be usable using any other method typically supported by composer-compatible packages.

For installation, run:

composer require authrocket/authrocket

# alternate:
php composer.phar require authrocket/authrocket

Or, add "authrocket/authrocket": "^2" to the require section of your composer.json and run composer install.

You can also download authrocket.phar, a .zip, or a .tar.gz of the latest release directly from GitHub: https://github.com/authrocket/authrocket-php/releases/latest

Client Basics

Using environment variables

If you are using environment variables to manage external services like AuthRocket, then it’s very easy to initialize the AuthRocket client:

$authrocket = \AuthRocket\AuthRocket::autoConfigure();

Ensure these environment variables are set:

# If only validating tokens
LOGINROCKET_URL    = https://SAMPLE.e2.loginrocket.com/

# If only validating tokens, but default JWT key type has been changed to HS256
LOGINROCKET_URL    = https://SAMPLE.e2.loginrocket.com/
AUTHROCKET_JWT_KEY = SAMPLE

# To use the AuthRocket API
AUTHROCKET_API_KEY = ks_SAMPLE
AUTHROCKET_URL     = https://api-e2.authrocket.com/v2
AUTHROCKET_REALM   = rl_SAMPLE  # optional, but recommended (see below)
# plus LOGINROCKET_URL and/or AUTHROCKET_JWT_KEY if also validating tokens

AUTHROCKET_API_KEY = ks_SAMPLE
Your AuthRocket API key. Required to use the API (but not if only performing JWT verification of login tokens).

AUTHROCKET_JWT_KEY = SAMPLE
Used to perform JWT signing verification of login tokens. Not required if validating all tokens using the API instead. Also not required if LOGINROCKET_URL is set and RS256 keys are being used, as public keys will be auto-retrieved. This is a realm-specific value, so like AUTHROCKET_REALM, set it directly if using multiple realms (see below).

AUTHROCKET_REALM = rl_SAMPLE
Sets an application-wide default realm ID. If you’re using a single realm, this is definitely easiest. Certain multi-tenant apps might use multiple realms. In this case, don’t set this globally, but directly when constructing the client (see below).

AUTHROCKET_URL = https://api-e2.authrocket.com/v2
The URL of the AuthRocket API server. This may vary depending on which cluster your service is provisioned on.

LOGINROCKET_URL = https://SAMPLE.e2.loginrocket.com/
The LoginRocket URL for your Connected App. Used for auto-retrieval of RS256 JWT keys (if AUTHROCKET_JWT_KEY is not set). If your app uses multiple realms, you may need to set this directly instead (see below). If you’re using a custom domain, this will be that domain and will not contain ‘loginrocket.com’.

If you are using multiple realms, we recommend building a new client for each realm, directly setting realm, jwtKey, and/or loginrocketUrl:

$authrocket = \AuthRocket\AuthRocket::autoConfigure([
  'realm'          => 'rl_SAMPLE',
  'jwtKey'         => 'SAMPLE',
  'loginrocketUrl' => 'https://SAMPLE.e2.loginrocket.com/'
]);

Similarly, if changing locales between requests, build a new client for each:

$authrocket = \AuthRocket\AuthRocket::autoConfigure([
  'locale' => 'es'
]);

Direct configuration

It’s also possible to configure the AuthRocket client instance directly:

$authrocket = new \AuthRocket\AuthRocket([
  'apiKey'         => 'ks_SAMPLE',
  'url'            => 'https://api-e2.authrocket.com/v2',
  'realm'          => 'rl_SAMPLE',
  'jwtKey'         => 'SAMPLE',
  'loginrocketUrl' => 'https://SAMPLE.e2.loginrocket.com/',
  'locale'         => 'en'
]);

Requests

See the AuthRocket API documentation for available APIs, parameters, and responses, all with PHP-specific examples.

Overview of common requests

Most resources support some or all of the below. Check specific APIs to confirm existence of specific functions.

List [resources]

// Retrieve multiple resources at once
$res = $authrocket->orgs()->all();
$res->results // Array of results
$res->results[0]['id'] // ID of the first returned resource

// Retrieve the first 20 resources
$res = $authrocket->orgs()->all([
  "max_results" => 20
]);

// Retrieve the next 20 resources
if ($res->hasMore()) {
  $res = $authrocket->orgs()->all([
    "max_results" => 20,
    "after" => $res->results[-1]['id']  // ID of the last resource previously received
  ]);
}

// A convenience function to retrieve the first resource when the ID isn't known.
// If there are no matching resources, returns null.
// Available for any resource that also offers all(), even if not documented separately.
$result = $authrocket->orgs()->first();
$result = $authrocket->orgs()->first([
  "state" => "active"
]);
$result->id // ID of the returned resource

Get a [resource]

$result = $authrocket->orgs()->find('org_SAMPLE');
$result->id // ID of the returned resource
$result->name // Name field of the returned resource
// throws an \AuthRocket\RecordNotFound error if ID not found

$result = $authrocket->orgs()->find('org_SAMPLE', [
  ... // other arguments
]);

Create a [resource]

$result = $authrocket->orgs()->create([
  "name" => "Widgets Inc"
]);
$result->hasErrors() // true if there were errors
$result->errors() // array of error messages
$result->errorMessages() // all error messages combined into one string
$result->id // ID of the new resource

Update a [resource]

$result = $authrocket->orgs()->update('org_SAMPLE', [
  "name" => "Widgets Inc"
]);
$result->hasErrors() // true if there were errors
$result->errors() // array of error messages
$result->errorMessages() // all error messages combined into one string
$result->id // ID of the updated resource
// throws an \AuthRocket\RecordNotFound error if ID not found

Delete a [resource]

$result = $authrocket->sessions()->delete('kss_SAMPLE');
$result = $authrocket->orgs()->delete('org_SAMPLE', [
  "force" => true
]);
$result->hasErrors() // true if there were errors
$result->errors() // array of error messages
$result->errorMessages() // all error messages combined into one string
$result->id // ID of the updated resource
// throws an \AuthRocket\RecordNotFound error if ID not found

Responses

APIs that return multiple results will return those results as an array named results.

$res = $authrocket->orgs()->all();
$res->results // Array of results
$res->results[0] // First result
$res->hasMore() // Are there more results available?

In this case, fields are accessed using array syntax.

$res->results[0]['id'] // ID of the first resource
$res->results[1]['name'] // Name field of the second resource

APIs that return a single result may access fields using arrow syntax or via fields.

$result = $authrocket->orgs()->find('org_SAMPLE');
$result->id // ID of the returned resource
$result->name // Name field of the returned resource
$result->fields['id'] // Alternate way to retrieve the ID

Errors and exceptions

Most errors are data validation errors (HTTP status 409 and 422). These errors are returned as part of $result and need to be checked directly.

The most common exception will be \AuthRocket\RecordNotFound which is thrown when a resource cannot be found, generally when the ID doesn’t exist. Exceptions can also be thrown when hitting rate limits or encountering network errors.

try {
  $result = $authrocket->orgs()->update('org_SAMPLE', [
    "name" => "Widgets Inc"
  ]);
  if ($result->hasErrors()) {
    // Use one of these to display/log the error messages
    $result->errors() // array of error messages
    $result->errorMessages() // all error messages combined into one string
  } else {
    // success
  }
} catch (\AuthRocket\RecordNotFound $e) {
  // ID not found
}

// Alternatively, catch all possible AuthRocket exceptions:
try {
  ...
} catch (\AuthRocket\Error $e) {
  ...
}