Realms

Fields

FieldValueReq/DefaultNotes
id id Auto-generated Realm's ID. Always starts with "rl_". Example: rl_USik0KJuMtajar2VwTJyQ
name string Required Name/title of the realm.
state active,
inactive
active
reference string Optional Field to map to your app's own ID.
custom hash Optional Hash of custom attributes.
username_validation_human standard,
email
standard Determines how User.username is validated for human type users.
require_unique_emails boolean true Check User.email for uniqueness.
api_key_prefix string Optional Default string prepended to auto-generated api_keys for Users.
api_key_policy encrypt,
hash
hash See below.
jwt_algo hs256,
rs256
hs256 Algorithm to use for signing JWTs.
jwt_fields array [] Extra fields to embed in login tokens. Valid values: custom, memberships, orgs.
jwt_key string Auto-generated Secret key (hs256) or public key (rs256) for verifying login tokens.
jwt_secret string Deprecated; use jwt_key.
session_type managed,
unmanaged
managed

See Session Concepts.

session_minutes integer 360 Validity time of login tokens, in minutes.
api_key_minutes integer 0 Validity time of tokens generated for api_keys, in minutes.
resource_links array See below.
request hash

Hash of request attributes to add to Event. See notes.

By default, accounts allow up to 100 realms. Contact support to request an increase.

api_key_policy

api_key_policy affects how Credential.api_key is stored. This only applies to users where user_type = 'api'.

The hash policy means that API keys are stored as one-way hashes, similar to passwords. They cannot be read again afterwards. This is the higher security option. On the other hand, many services that offer an API to their customers desire to show that API key to the end user on-demand. This is not possible if they’ve been hashed. If we generate the API key and it’s hashed, it will be returned to you once, when created. Afterward, it’s flushed from memory and cannot be retrieved again.

The encrypt policy addresses this by storing all API keys using two-way encryption instead. (We handle the encryption transparently any time you retrieve the API user and read the API key, so it’s no further work on your part.)

We generally recommend the encrypt policy as it’s more versatile. The hash policy is intended for services with particularly high security needs–high enough to offset the reduced versatility.

jwt_fields

Login (JWT) tokens embed a fair bit of user data, reducing the need for your app to query our servers. User profile data is included by default. Adding memberships includes Membership data. Adding orgs adds Org data (requires memberships to also be present). Adding custom adds custom attributes for the User, and if also included, the Membership and Org.

Tokens have the potential to get quite large when adding extra data, especially if there are many custom attributes or if the User has several Memberships. If your Users have only a handful of attributes or 1-3 Memberships, you should be fine. If they have more, be sure to verify that your entire app-server stack is prepared to handle the long tokens (typically 1-10KB). If storing tokens inside cookies, cookies have a total limit of 4K. Some webservers or proxies have difficulty with URLs or headers > 1K, which can affect query parameters, cookies, or other headers.

  • Default - User profile data, including username, first_name, and last_name.
  • memberships - Adds Membership permissions and Org IDs.
  • orgs - Adds Org names.
  • custom - Adds custom attributes for User, and optionally the Membership and Org.

Hint: Tokens are cryptographically signed, but not encrypted. Tokens should generally be transmitted over https, but even then don’t use custom or other extensions if it’s unsafe for your user to read their own data.

session_minutes

Used when calculating the expiration time of a login token generated during a normal login.

When session_type is unmanaged, valid values are 1 minute to 2 years (1052640 minutes). 0 is also valid and causes no expiration time to be set at all.

When session_type is managed, valid values are 1 minute to 1 year (527040 minutes).

api_key_minutes

Used when calculating the expiration time of a login token generated when authenticating with an api_key.

Valid values are 1 minute to 2 years (1052640 minutes). 0 is also valid and means no limit at all.

resource_links

Resource links describes links/buttons to be automatically added to the AuthRocket UI. It is an array of hashes/dictionaries:

[{"resource" : "org",
  "title" : "Manage account",
  "url" : "https://yourapp.com/admin/org/{{reference}}"
}]

resource must be one of: org, user.
url will automatically parse select variables: {{id}}, {{reference}}, {{realm_id}}

Custom attributes

See Custom attributes under Users for details.

Permissions

MethodPermissions
List, Get read
Update, Reset admin_realm
Create, Delete admin_all_realms

List realms

List all realms on the current account.

Parameters

ParamValueDefault
reference reference Filter by reference; must be an exact match
state state Filter by state
after realm_id ID of the last realm you've seen
max_results integer 100 Range: 1-1000
sort id,
name
name
direction asc,
desc
asc
expand custom

Include custom in the response

Request

Example
GET /v1/realms
$res = $client->realms()->all();
AuthRocket::Realm.all

Response

Example

Status: 200

{ "more_results" : false,
  "collection" : [
    { "id" : "rl_0v1zTHXhtNgmDaXaDYSAqx",
      "name" : "AcmeApp SSO",
      "reference" : null,
      "state" : "active",
      "object" : "realm"
    }
  ]
}
var_dump($res->results);
  array(1) {
    [0]=>
    array(5) {
      ["id"]=> string(25) "rl_0v2FcFc5IN79xazvkgLhnX"
      ["name"]=> string(23) "Acme App+"
      ["reference"]=> NULL
      ["state"]=> string(6) "active"
      ["object"]=> string(5) "realm"
    }
  }
[#<AuthRocket::Realm:0x3fde5d71d448>
  id: "rl_0v2FcFc5IN79xazvkgLhnX",
  attribs: {
    "name"=>"Acme App+",
    "reference"=>nil,
    "state"=>"active",
    "object"=>"realm"
  },
  metadata: {
    "more_results"=>false
  }
]

Get a realm

Retrieve a specific realm.

Request

Example
GET /v1/realms/:realm_id
$res = $client->realms()->find('rl_0v2FcFc5IN79xazvkgLhnX');
AuthRocket::Realm.find 'rl_0v2FcFc5IN79xazvkgLhnX'

Response

Example

Status: 200

{ "id" : "rl_0v1zTHXhtNgmDaXaDYSAqx",
  "name" : "AcmeApp SSO",
  "reference" : null,
  "custom" : {},
  "state" : "active",
  "object" : "realm",
  "api_key_policy" : "hash",
  "api_key_prefix" : "pk-",
  "username_validation_human" : "standard",
  "require_unique_emails" : true,
  "jwt_algo" : "hs256",
  "jwt_fields" : [],
  "jwt_key" : "jsk_m2y4UYnjRCXzuZVq57bJJSDoqOFMuQCFmLp4Nh9gcbk",
  "session_type":  "managed",
  "session_minutes" : 360,
  "api_key_minutes" : 0
}
var_dump($res->fields);
  array(16) {
    ["id"]=> string(25) "rl_0v2FcFc5IN79xazvkgLhnX"
    ["name"]=> string(23) "Acme App+"
    ["reference"]=> NULL
    ["custom"]=> array(0) {}
    ["state"]=> string(6) "active"
    ["object"]=> string(5) "realm"
    ["api_key_policy"]=> string(4) "hash"
    ["api_key_prefix"]=> NULL
    ["username_validation_human"]=> string(8) "standard"
    ["require_unique_emails"]=> bool(true)
    ["jwt_algo"]=> string(5) "hs256"
    ["jwt_fields"]=> array(0) {}
    ["jwt_key"]=> string(47) "jsk_m2y4UYnjRCXzuZVq57bJJSDoqOFMuQCFmLp4Nh9gcbk"
    ["session_type"]=> string(7) "managed"
    ["session_minutes"]=> int(360)
    ["api_key_minutes"]=> int(0)
  }
#<AuthRocket::Realm:0x3fde5d71d448>
  id: "rl_0v2FcFc5IN79xazvkgLhnX",
  attribs: {
    "name"=>"Acme App+",
    "reference"=>nil,
    "custom"=>{},
    "state"=>"active",
    "object"=>"realm",
    "api_key_policy"=>"hash",
    "api_key_prefix"=>nil,
    "username_validation_human"=>"standard",
    "require_unique_emails"=>true,
    "jwt_algo"=>"hs256",
    "jwt_fields"=>[],
    "jwt_key"=>"jsk_m2y4UYnjRCXzuZVq57bJJSDoqOFMuQCFmLp4Nh9gcbk",
    "session_type"=>"managed",
    "session_minutes"=>360,
    "api_key_minutes"=>0
  }

Create a realm

Create a new realm.

Request

Example
POST /v1/realms
{ "realm" :
  { "name" : "AcmeApp SSO",
    "require_unique_emails" : true
  }
}
$res = $client->realms()->create([
  "name" => "AcmeApp SSO",
  "require_unique_emails" => true
]);
realm = AuthRocket::Realm.create(
  name: 'AcmeApp SSO',
  require_unique_emails: true
)

Response

Example

Status: 201, with same body as Get a Realm.

On success, returns same object as Get a Realm.

On failure, returns an object with errors:

$res->hasErrors();
// => true
var_dump($res->errors);
  array(1) {
    [0]=> string(31) "Name can't be blank"
  }

On success, returns same object as Get a Realm.

On failure, returns an object without an id, but with errors:

# => #<AuthRocket::Realm:0x3fde5d77e0f4> id: nil, ...
realm.errors?
# => true
realm.valid?
# => false
realm.errors
# => ["Name can't be blank"]

Events

Triggers realm.created and auth_provider.created events.

Update a realm

Update a realm’s attributes. Only provided attributes are changed.

Request

Example
PUT /v1/realms/:realm_id
{ "realm" :
  { "name" : "Acme App SSO"
  }
}
$res = $client->realms()->update('rl_0v6IVFUFLEM55OtsHWAOHQ', [
  "name" => "Acme App SSO"
]);
realm=AuthRocket::Realm.find 'rl_0v6IVFUFLEM55OtsHWAOHQ'
realm.save reference: '123456'

Response

Example

Status: 200, with same body as Get a Realm.

On success, returns same object as Get a Realm.

On failure, returns an object with errors:

$res->hasErrors();
// => true
var_dump($res->errors);
  array(1) {
    [0]=> string(31) "Name can't be blank"
  }

On success, returns same object as Get a Realm.

On failure, returns false:

# => false
realm.errors
# => ["Name can't be blank"]

Events

Triggers a realm.updated event.

Delete a realm

Deletes a realm and everything it contains.

Request

Example
DELETE /v1/realms/:realm_id
$res = $client->realms()->delete('rl_0v6IVFUFLEM55OtsHWAOHQ');
realm=AuthRocket::Realm.find 'rl_0v6IVFUFLEM55OtsHWAOHQ'
realm.delete

Response

Example

Status: 202

On success, returns an object with no errors.

On failure, returns an object with errors.

$res->hasErrors();
// => true or false

On success, returns original object.

On failure, returns false.

Events

Triggers a realm.deleted event. Does not trigger events for associated Users, Orgs, etc.

Reset a realm

Resets a realm by clearing most/all of what it contains. By default deletes all users and orgs, but keeps app hooks, auth providers, and login policies (connected apps).

Events associated with deleted objects are also removed.

Deleted data is not recoverable–use with caution. Useful for development and running tests.

Note: this runs asynchronously. Any records added to the realm while the reset is still running have the potential to be deleted.

Request

Example
POST /v1/realms/:realm_id/reset
{ "app_hooks" : false,
  "auth_providers" : false,
  "login_policies" : false,
  "orgs" : true,
  "users" : true
}
$res = $client->realms()->reset('rl_0v6IVFUFLEM55OtsHWAOHQ', [
  "app_hooks" => false,
  "auth_providers" => false,
  "login_policies" => false,
  "orgs" => true,
  "users" => true
]);
realm=AuthRocket::Realm.find 'rl_0v6IVFUFLEM55OtsHWAOHQ'
realm.reset! orgs: true, users: true

Response

Example

Status: 202, with same response as Get a Realm.

On success, returns same object as Get a Realm.

On failure, returns an object with errors.

$res->hasErrors();
// => true

On success, returns same object as Get a Realm.

On failure, raises an exception.

Events

Does not trigger any events.

Questions? Find a Typo? Get in touch.