Stormpath REST API Product Guide

Stormpath is a User Management API that reduces development time with instant-on, scalable user infrastructure. Stormpath’s intuitive API and expert support make it easy for developers to authenticate, manage and secure users and roles in any application.

To get started with the basics of Stormpath quickly, check out the REST API Quickstart Guide. For a more complete understanding and reference of the full Stormpath service, read on.


What is Stormpath?

Stormpath is the first easy, secure user management and authentication service for developers.

Fast and intuitive to use, Stormpath enables plug-and-play security and accelerates application development on any platform.

Built for developers, it offers an easy API, open source SDKs, and an active community. The flexible cloud service can manage millions of users with a scalable pricing model that is ideal for projects of any size.

By offloading user management and authentication to Stormpath, developers can bring new applications to market faster, reduce development and operations costs, and protect their users with best-in-class security.

Overview

High-level Architecture

Stormpath is a REST API service. You use a REST client (or one of our open-source language-specific SDKs) inside your application to communicate with the Stormpath API. Stormpath’s API allows you to offload user management and authentication by helping you do the following:

  • Account registration, complete with sending welcome emails
  • Account email verification (send email –> user clicks a link –> their account is verified and they can login)
  • Secure password storage with continuously updated cryptography best practices
  • Password reset (send email –> user clicks a link –> sets new password –> account password encrypted and stored securely)
  • Account login (authentication)
  • Seamless integration with LDAP and Active Directory – you’ll never have to worry about integrating your application with them again
  • A complete administrative user interface to allow you to manage your applications, directories, accounts and groups
  • And more…

When building your applications in the past, how much time have you spent writing some or all of this functionality? It is quite a large amount of work, and this logic has nothing to do with why you’re writing your application! But you need it, and you need it to be secure.

By offloading all of this effort to Stormpath, a service with deep security roots, you can quickly get back to writing your actual application and never worry about password attacks again.

Core Concepts

Stormpath has five core concepts, and everything else in the Stormpath REST API exists to support them:

  • Applications
  • Directories
  • Groups
  • Accounts
  • Tenants
  • Account Stores

These resources and their relationships are manageable by the REST API as described in this document, but you may also manage them via the Stormpath Admin Console user interface.

Applications

An Application is a real-world software application that communicates with Stormpath to offload user management, authentication, and security workflows. Each application that communicates with Stormpath is represented within Stormpath so you may manage its security needs.

You can assign one or more Account Stores to an Application. Accounts within assigned account stores may login to the application.

Account Stores

An Account Store is a generic term for either a Directory or a Group. Directories and Groups are both are considered ‘account stores’ because they both contain, or ‘store’, Accounts.

  • Directories

    A Directory is a top-level storage container of Accounts and Groups. A Directory also manages security policies (like password strength) for the Accounts it contains. Stormpath supports two types of Directories: natively hosted ‘Cloud’ directories that originate in Stormpath and ‘Mirror’ directories that act as secure mirrors or replicas of existing directories outside of Stormpath, for example LDAP or Active Directory servers.

    Directories can be used to cleanly manage segmented account populations – for example, you might use one Directory for company employees and another Directory for customers, each with its own security policies.

  • Groups

    A Group is a uniquely named collection of Accounts within a Directory. Each Group within a Directory must have a unique name and may contain Accounts within their own Directory. Groups are mostly used for security and access control, often called Role-Based Access Control.

    For example, you might only show a particular user interface button if an Account is in the ‘Administrators’ Group. It might be helpful to note that Stormpath does not have an explicit Role concept – you use Stormpath Groups as Roles for Role-Based Access Control.

Accounts

An Account is a unique identity within a Directory, with a unique username and/or email address. An account can log in to applications using either the email address or username associated with it. Accounts can represent people end-users, but they can also be used to represent services, machines, or any ‘entity’ that needs to login to a Stormpath-enabled application.

Tenants

Stormpath is a multi-tenant software service. When you sign up for Stormpath, a private data ‘space’, called a Tenant, is created for you. This private tenant space contains all of the data you own, including your applications, directories, accounts and groups and more. The Tenant concept is mostly ‘behind the scenes’ and you don’t need to use it all that often, but sometimes it is necessary or useful to use directly.


REST API General Concepts

Base URL

All URLs referenced in the API documentation begin with the following base URL:

https://api.stormpath.com/v1

Authentication

Every request to the Stormpath REST API must be authenticated with an API key over HTTPS. HTTP is not supported. If you want to make a REST request to Stormpath, we assume you have already:

  1. Signed up for Stormpath.
  2. Obtained your API key.

When you have an API key, you can choose one of two ways to authenticate with Stormpath:

Security Notice: Any account that can access the Stormpath application within the Stormpath Admin Console has full administrative access to your Stormpath data and settings, including access to the REST API if they have an API Key.

Assign user accounts to Stormpath, through account stores, wisely.

Basic Authentication over HTTPS

Most clients (including web browsers) show a dialog or prompt for you to provide a username and password for HTTP Basic Authentication.

When using an API key with basic authentication, the API key id is the username and the API key secret is the password:

HTTP basic username: apiKey.id value
HTTP basic password: apiKey.secret value

For example, if using curl:

curl -u $YOUR_API_KEY_ID:$YOUR_API_KEY_SECRET \
     -H "Accept: application/json" \
     -L https://api.stormpath.com/v1/tenants/current

or perhaps httpie (which assumes application/json by default):

http -a $YOUR_API_KEY_ID:$YOUR_API_KEY_SECRET https://api.stormpath.com/v1/tenants/current

Digest Authentication Over HTTPS

Stormpath also supports a more secure authentication scheme known as digest authentication. This approach computes a cryptographic digest of the request and sends the digest value along with the request. If the transmitted digest matches what the Stormpath API server computes for the same request, the request is authenticated.

This technique is especially secure because the API key secret is never transmitted outside of the application, making it extremely difficult for anything (or anyone) outside of the application to interfere with a request or see the secret.

We recommend using digest authentication whenever possible because it is inherently more secure. However, due to its complexity, it might not be feasible for some projects.

All Stormpath SDKs (currently Java, Ruby, PHP, and Python) use this more secure digest authentication so we recommend that you use the SDKs whenever possible. However, if we do not yet have an SDK for your programming language, you should use basic authentication over HTTPS.

Finally, if you would like to use Stormpath digest authentication in a programming language that Stormpath does not yet support, you can attempt to port the algorithm to that language. You can try to replicate the algorithm and use Stormpath existing code as examples to help:

If you port the algorithm to other languages, please let us know. We are happy to help. Email us at support@stormpath.com and we will help as best as we can.

The Stormpath SAuthc1 digest algorithm is NOT the same as RFC 2617 HTTP digest authentication. The Stormpath SAuthc1 digest-based authentication scheme is more secure than standard HTTP digest authentication.

Resource Format

The Stormpath REST API currently only supports JSON resource representations. If you would like other formats supported, please email us at support@stormpath.com to let us know!

Creating Resources

You create a resource by submitting an HTTP POST to a resource URI. Any POST body must be represented as JSON.

Request

Requests that contain body content must specify the HTTP Content-Type header with a value of application/json.

An example Create POST Request:

curl -X POST \
     -u $API_KEY_ID:$API_KEY_SECRET \
     -H "Accept: application/json" \
     -H "Content-Type: application/json;charset=UTF-8" \
     -d '{
           "name": "Desired name",
           "description": "Desired description",
           "status": "enabled"
         }` \
     "https://api.stormpath.com/v1/tenants/$YOUR_TENANT_ID/applications"

Response

Create POST responses contain:

Item Description
HTTP Status Code The code indicates general success or failure of the request.
HTTP Headers Various response headers are set relevant to the particular request.
Response Body Successful requests contain the created entity resource representation, while failed requests show an error representation.

Possible Create POST Response Status Codes include:

Response Code Description
201 CREATED The request was successful, we created a new resource, and the response body contains the representation. The Location header contains the new resource’s canonical URI.
400 BAD REQUEST The data given in the POST or PUT failed validation. Inspect the response body for details.
401 UNAUTHORIZED Authentication credentials are required to access the resource. All requests must be authenticated.
403 FORBIDDEN The supplied authentication credentials are not sufficient to access the resource.
404 NOT FOUND We could not locate the resource based on the specified URI.
405 METHOD NOT ALLOWED POST is not supported for the resource.
409 CONFLICT You cannot create or update a resource because another resource already exists or conflicts with one you are submitting.
415 UNSUPPORTED MEDIA TYPE You did not specify the request Content-Type header to have a value of application/json. Only application/json is currently supported.
429 TOO MANY REQUESTS Your application is sending too many simultaneous requests.
500 SERVER ERROR We could not create or update the resource. Please try again.
503 SERVICE UNAVAILABLE We are temporarily unable to service the request. Please wait for a bit and try again.

Example Create POST Response:

HTTP/1.1 201 Created
Location: https://api.stormpath.com/v1/applications/WpM9nyZ2TbaEzfbRvLk9KA
Content-Type: application/json;charset=UTF-8;

{
  "href": "https://api.stormpath.com/v1/applications/WpM9nyZ2TbaEzfbRvLk9KA",
  "name": "Desired name",
  "description": "Desired description",
  "status": "ENABLED",
  "tenant": {
    "href": "https://api.stormpath.com/v1/tenants/cJoiwcorTTmkDDBsf02AbA"
  },
  "accounts": {
    "href": "https://api.stormpath.com/v1/applications/WpM9nyZ2TbaEzfbRvLk9KA/accounts"
  },
  "groups": {
    "href": "https://api.stormpath.com/v1/applications/WpM9nyZ2TbaEzfbRvLk9KA/groups"
  },
  "loginAttempts": {
    "href": "https://api.stormpath.com/v1/applications/WpM9nyZ2TbaEzfbRvLk9KA/loginAttempts"
  },
  "accountStoreMappings": {
    "href": "https://api.stormpath.com/v1/applications/WpM9nyZ2TbaEzfbRvLk9KA/accountStoreMappings"
  },
  "defaultAccountStoreMapping": {
    "href": "https://api.stormpath.com/v1/accountStoreMappings/7bKZXzXxHFrVeNOExAmPlE"
  },
  "defaultGroupStoreMapping": {
    "href": "https://api.stormpath.com/v1/accountStoreMappings/7bKZXzXxHFrVeNOExAmPlE"
  },
  "passwordResetTokens": {
    "href": "https://api.stormpath.com/v1/applications/WpM9nyZ2TbaEzfbRvLk9KA/passwordResetTokens"
  },
}

Retrieving Resources

Request

You can retrieve a resource representation by GETting its url.

An example API GET:

curl -u $API_KEY_ID:$API_KEY_SECRET \
     -H "Accept: application/json" \
     -L https://api.stormpath.com/v1/tenants/current

Response

GET responses contain:

Item Description
HTTP Status Code The code indicates general success or failure of the request.
HTTP Headers Various response headers are set relevant to the particular request.
Response Body Successful requests contain the requested entity resource representation, while failed requests show an error representation.

Possible GET Response Status Codes include:

Response Code Description
200 OK The request was successful and the response body contains the representation requested.
302 FOUND A common redirect response; you can GET the representation at the URI in the location response header.
304 NOT MODIFIED Your client’s cached version of the representation is still up to date.
401 UNAUTHORIZED Authentication credentials are required to access the resource. All requests must be authenticated.
403 FORBIDDEN The supplied authentication credentials are not sufficient to access the resource.
404 NOT FOUND We could not locate the resource based on the specified URI.
429 TOO MANY REQUESTS Your application is sending too many simultaneous requests.
500 SERVER ERROR We could not return the representation due to an internal server error.
503 SERVICE UNAVAILABLE We are temporarily unable to service the request. Please wait for a bit and try again.

An example API GET Response:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8;

{
  "href": "https://api.stormpath.com/v1/tenants/cJoiwcorTTmkDDBsf02AbA",
  "name": "My Tenant",
  "key": "myTenant"
}

Updating Resources

If you want to update a resource, submit an HTTP POST to a resource URI. Any POST body must be represented as JSON. You can submit one or more attributes of a resource, but at least one attribute must be specified.

Request

Requests that contain body content must specify the HTTP Content-Type header with a value of application/json.

An example Update (HTTP POST) request, updating a single attribute:

curl -X POST \
     -u $API_KEY_ID:$API_KEY_SECRET \
     -H "Accept: application/json" \
     -H "Content-Type: application/json;charset=UTF-8" \
     -d '{
           "name": "New name"
         }' \
     "https://api.stormpath.com/v1/applications/$APPLICATION_ID"

Notice that the post body in this particular example contains only a single JSON name/value pair, although application resources have multiple name/value pairs.

Updates enable updating one or more resource attribute values. At least one resource attribute value must be specified.

Response

Update POST responses contain:

Item Description
HTTP Status Code The code indicates general success or failure of the request.
HTTP Headers Various response headers are set relevant to the particular request.
Response Body Successful requests contain the updated entity resource representation, while failed requests show an error representation.

Possible Update POST Response Status Codes include:

Response Code Description
200 OK The request was successful, we updated the resource, and the response body contains the resource full representation.
400 BAD REQUEST The data given in the POST request body failed validation. Inspect the response body for details.
401 UNAUTHORIZED The supplied credentials, if any, are not sufficient to create or update the resource.
403 FORBIDDEN The supplied authentication credentials are not sufficient to access the resource.
404 NOT FOUND We could not locate the resource based on the specified URI.
405 METHOD NOT ALLOWED POST is not supported for the resource.
409 CONFLICT You cannot create or update a resource because another resource already exists or conflicts with one you are submitting.
415 UNSUPPORTED MEDIA TYPE You did not specify the request Content-Type header to have a value of application/json. Only application/json is currently supported.
429 TOO MANY REQUESTS Your application is sending too many simultaneous requests.
500 SERVER ERROR We could not create or update the resource. Please try again.
503 SERVICE UNAVAILABLE We are temporarily unable to service the request. Please wait for a bit and try again.

Example Update POST response:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8;

{
  "href": "https://api.stormpath.com/v1/applications/WpM9nyZ2TbaEzfbRvLk9KA",
  "name": "New name",
  "description": "Really. The best application ever.",
  "status": "ENABLED",
  "tenant": {
    "href": "https://api.stormpath.com/v1/tenants/cJoiwcorTTmkDDBsf02AbA"
  },
  "accounts": {
    "href": "https://api.stormpath.com/v1/applications/WpM9nyZ2TbaEzfbRvLk9KA/accounts"
  },
  "groups": {
    "href": "https://api.stormpath.com/v1/applications/WpM9nyZ2TbaEzfbRvLk9KA/groups"
  },
  "loginAttempts": {
    "href": "https://api.stormpath.com/v1/applications/WpM9nyZ2TbaEzfbRvLk9KA/loginAttempts"
  },
  "accountStoreMappings": {
    "href": "https://api.stormpath.com/v1/applications/WpM9nyZ2TbaEzfbRvLk9KA/accountStoreMappings"
  },
  "defaultAccountStoreMapping": {
    "href": "https://api.stormpath.com/v1/accountStoreMappings/7bKZXzXxHFrVeNOExAmPlE"
  },
  "defaultGroupStoreMapping": {
    "href": "https://api.stormpath.com/v1/accountStoreMappings/7bKZXzXxHFrVeNOExAmPlE"
  },
  "passwordResetTokens": {
    "href": "https://api.stormpath.com/v1/applications/WpM9nyZ2TbaEzfbRvLk9KA/passwordResetTokens"
  },
}

Deleting Resources

To delete a resource, make an HTTP DELETE request to the resource URL. Note that not all Stormpath REST API resources support delete.

Request

An example DELETE request:

curl -X DELETE -u $API_KEY_ID:$API_KEY_SECRET "https://api.stormpath.com/v1/applications/$APPLICATION_ID"

Response

Possible DELETE Response Status Codes include:

Response Code Description
204 NO CONTENT The request was successful; the resource was deleted. The deleted resource representation will not be returned.
401 UNAUTHORIZED The supplied credentials, if any, are not sufficient to create or update the resource.
403 FORBIDDEN The supplied authentication credentials are not sufficient to access the resource.
404 NOT FOUND We could not locate the resource based on the specified URI.
405 METHOD NOT ALLOWED DELETE is not supported for the resource.
429 TOO MANY REQUESTS Your application is sending too many simultaneous requests.
500 SERVER ERROR We could not create or update the resource. Please try again.
503 SERVICE UNAVAILABLE We are temporarily unable to service the request. Please wait for a bit and try again.

Example DELETE response:

HTTP/1.1 204 No Content

HTTP Method Overloading

The Stormpath REST API uses HTTP GET, POST, PUT, and DELETE methods. Because some HTTP clients do not support PUT and DELETE methods, you can simulate them by sending a POST request to a resource endpoint with a _method query string parameter. The parameter value can be DELETE (_method=DELETE) or PUT (_method=PUT).

For example, if you want to delete a particular application resource, you would ordinarily execute an HTTP DELETE request:

curl -X DELETE -u $API_KEY_ID:$API_KEY_SECRET "https://api.stormpath.com/v1/applications/$APPLICATION_ID"

But if your HTTP client only supports GET and POST, you can send a POST request with the _method query string parameter:

curl -X POST -u $API_KEY_ID:$API_KEY_SECRET "https://api.stormpath.com/v1/applications/$APPLICATION_ID?_method=DELETE"

Errors

REST API responses indicating an error or warning are represented by a proper response HTTP status code (403, 404, etc). Additionally, a response body is provided containing the following information:

Attribute Description Type
status The corresponding HTTP status code. Integer
code A Stormpath-specific error code that can be used to obtain more information. Integer
message A simple, easy to understand message that you can show directly to your application end-user. String
developerMessage A clear, plain text explanation with technical details that might assist a developer calling the Stormpath API. String
moreInfo A fully qualified URL that may be accessed to obtain more information about the error. String

Example

Example request for a resource that does not exist:

curl -u $API_KEY_ID:$API_KEY_SECRET \
     -H "Accept: application/json" \
     https://api.stormpath.com/v1/applications/thisApplicationDoesNotExist

Example response:

HTTP/1.1 404 Not Found

{
  "status": 404,
  "code": 404,
  "message": "Oops! The application you specified cannot be found.",
  "developerMessage": "The specified Application cannot be found. If you accessed this url via a stale href reference, it might be helpful to acquire the tenant's Application Collection Resource to obtain the current list of applications.",
  "moreInfo": "http://docs.stormpath.com/errors/404"
}

Error Code Reference

The Stormpath Error Code Reference provides the list of all Stormpath-specific error codes and their meanings.

Collection Resources

A Collection Resource is a resource containing other resources. It is known as a Collection Resource because it is itself a first class resource – it has its own attributes similar to any other resource in addition to the instances it contains.

If you want to interact with multiple resources, you must do so with a Collection Resource. Collection Resources also support additional behavior specific to collections, such as pagination, sort ordering, and searching.

Collection Resource Attributes

Attribute Description Type
href The fully qualified location URI of the Collection Resource. String
offset The zero-based starting index in the entire collection of the first item to return. The default value is 0. This is a pagination-specific attribute. Integer
limit The maximum number of collection items to return for a single request. Minimum value is 1. The maximum value is 100 and the default value is 25. This is a pagination-specific attribute. Integer
items An array containing the current page of resources. The size of this array can be less than the requested limit. For example, if the limit requested is greater than the maximum allowed or if the response represents the final page in the total collection and the item count of the final page is less than the limit. This is a pagination-specific attribute. Array

Request

To acquire a Collection Resource, submit an HTTP GET to the Collection Resource URI.

Pagination

If a Collection Resource represents a large enough number of resource instances, it will not include them all in a single response. Instead a technique known as pagination is used to break up the results into one or more pages of data. You can request additional pages as separate requests.

Query Parameters

There are two optional query parameters that may be specified to control pagination:

  • offset: The zero-based starting index in the entire collection of the first item to return. Default is 0.
  • limit: The maximum number of collection items to return for a single request. Minimum value is 1. Maximum value is 100. Default is 25.

Example Collection Resource Request

An example GET request for a Collection Resource using pagination:

curl -u $API_KEY_ID:$API_KEY_SECRET \
     -H "Accept: application/json" \
     "https://api.stormpath.com/v1/tenants/$TENANT_ID/applications?offset=10&limit=40"

This example requests a tenant’s applications Collection Resource from the server with page results starting at index 10 (the 11th element), with a maximum of 40 total elements.

Example Collection Resource Response

HTTP/1.1 200 OK

{
  "href": "https://api.stormpath.com/v1/tenants/cJoiwcorTTmkDEXAMPLE/applications?offset=10&limit=40"
  "offset": 10,
  "limit": 40,
  "items" : [
    {
      ... Application 10's name/value pairs ...
    },
    ...,
    {
      ... Application 49's name/value pairs ...
    }
  ]
}

Sorting

A request for a Collection Resource can contain an optional orderBy query parameter. The query parameter value is a URL-encoded comma-delimited list of ordering statements.

For example, a sorted request (where %2C is the URL encoding for the comma character) might look like this:

curl -u $API_KEY_ID:$API_KEY_SECRET \
     -H "Accept: application/json" \
     https://api.stormpath.com/v1/accounts?orderBy=orderStatement1%2CorderStatement2%2C...%2CorderStatementN

When URL-decoded, the URL looks like this:

https://api.stormpath.com/v1/accounts?orderBy=orderStatement1,orderStatement2,...,orderStatementN

Each orderStatement is defined as follows:

orderStatement ::= sortableAttributeName optionalAscendingOrDescendingStatement

where:

  • sortableAttributeName is the name of a sortable attribute of a resource in the items array. Sortable attributes are primitives (non-complex and non-link) attributes, such as integers and strings.
  • optionalAscendingOrDescendingStatement is composed of the following:
    • a space character (%20 URL encoded) followed by:
    • the token asc (ascending) or desc (descending)

If the optionalAscendingOrDescendingStatement parameter is not included (the query parameter value is a sortable attribute name only), asc is assumed by default.

For example, to get all accounts of an application and order the results by surname ascending and then givenName descending:

curl -u $API_KEY_ID:$API_KEY_SECRET \
     -H "Accept: application/json" \
     "https://api.stormpath.com/v1/applications/someRandomId/accounts?orderBy=surname%2CgivenName%20desc"

Which, if URL decoded, the URL would look like this:

https://api.stormpath.com/v1/applications/someRandomId/accounts?orderBy=surname,givenName desc

Notice the surname order statement does not specify asc or desc, implying asc by default.

Search

You can search for specific resources within a Collection Resource by using certain query parameters to specify your search criteria.

There are currently two different types of searches that might be performed: a generic Filter-based search and a more targeted Attribute-based search. Both options support result ordering, pagination, and link expansion.

Currently, a REST search request must be targeted at resources of the same type. For example, a search can be performed across accounts or groups, but not both at the same time.

Because the Stormpath REST API always represents one or more resources of the same type as a Collection Resource, a REST search is always sent to a Collection Resource endpoint.

Filter Search

A filter search consists of specifying a q query parameter and a corresponding search value on a Collection Resource URL:

curl -u $API_KEY_ID:$API_KEY_SECRET \
     -H "Accept: application/json" \
     "https://api.stormpath.com/v1/someCollection?q=some+criteria"

For example, to search across an application’s accounts for any account that has a searchable attribute containing the text ‘Joe’:

curl -u $API_KEY_ID:$API_KEY_SECRET \
     -H "Accept: application/json" \
    "https://api.stormpath.com/v1/applications/someAppId/accounts?q=Joe"

Matching Logic

If the entered criteria, through a case-insensitive comparison, exists within (or is equal to) any viewable attribute on an instance in the collection, that instance is included in the query results. Only instances visible to the current caller (owned by the caller’s tenant), are returned in the query results.

For example, consider the following query:

curl -u $API_KEY_ID:$API_KEY_SECRET \
     -H "Accept: application/json" \
     "https://api.stormpath.com/v1/accounts?q=Joe"

This returns all accounts where:

  • Each account is owned by the caller’s tenant
  • The account givenName equals or contains ‘joe’ (case insensitive) OR
  • The account surname equals or contains ‘joe’ (case insensitive) OR
  • The account email equals or contains ‘joe’ (case insensitive) OR
  • … etc …

In other words, each attribute comparison is similar to a ‘like’ operation in traditional RDBMS contexts. For example, if SQL was used to execute the query, it might look like this:

select * from my_tenant_accounts where
    (lower(givenName) like '%joe%' OR
     lower(surname) like '%joe%' OR
     lower(email) like '%joe%' OR ... );

Attribute Search

Attribute-based search is the ability to find resources based on full and partial matching of specific individual resource attributes:

curl -u $API_KEY_ID:$API_KEY_SECRET \
     -H "Accept: application/json" \
     "https://api.stormpath.com/v1/someCollection?anAttribute=someValue&anotherAttribute=anotherValue"

For example, to search an application’s accounts for an account with a givenName of Joe:

curl -u $API_KEY_ID:$API_KEY_SECRET \
     -H "Accept: application/json" \
     "https://api.stormpath.com/v1/applications/someAppId/accounts?givenName=Joe"

Matching Logic

Attribute-based queries use standard URI query parameters and function as follows:

  • Each query parameter name is the same name of a searchable attribute on an instance in the Collection Resource.
  • A query parameter value triggers one of four types of matching criteria:
    • No asterisk at the beginning or end of the value indicates a direct case-insensitive match.
    • An asterisk only at the beginning of the value indicates that the case-insensitive value is at the end.
    • An asterisk only at the end of the value indicates that the case-insensitive value is at the beginning.
    • An asterisk at the end AND at the beginning of the value indicates the value is contained in the string.

For example, consider the following query:

curl -u $API_KEY_ID:$API_KEY_SECRET \
     -H "Accept: application/json" \
     "https://api.stormpath.com/v1/accounts?givenName=Joe&middleName=*aul&surname=*mit*&email=joePaul*&status=disabled"

This returns all accounts where:

  • Each account is owned by the caller tenant.
  • The account givenName is equal to ‘Joe’ (case insensitive) AND
  • The account middleName ends with ‘aul’ (case insensitive) AND
  • The account surname equals or contains ‘mit’ (case insensitive) AND
  • The account email starts with with ‘joePaul’ (case insensitive) AND
  • The account status equals ‘disabled’ (case insensitive).

For resources with a status attribute, status query values must be the exact value. For example, enabled or disabled must be passed and fragments such as ena, dis, bled are not acceptable.

Links

REST resources that reference other resources, such as an account referencing its parent directory, represent the references as a Link object.

A Link is an object nested within an existing resource representation that has, at a minimum, an href attribute.

The href attribute is the fully qualified location URI of the linked resource.

Example Link in JSON:

{
  "href": "https://api.stormpath.com/v1/directories/S2HZc7gXTumVYEXAMPLE"
}

This JSON object structure is called a link as it provides a similar functionality to more familiar HTML Anchors, often called hyperlinks or just ‘links’ for short.

The following example account resource has four links – groups, groupMemberships, directory, and tenant:

{
  "href": "https://api.stormpath.com/v1/accounts/ZugcG3JHQFOTKGEXAMPLE",
  "username": "lonestarr",
  "email": "[email protected]",
  "fullName": "Lonestarr Schwartz",
  "givenName": "Lonestarr",
  "middleName": "",
  "surname": "Schwartz",
  "status": "ENABLED",
  "emailVerificationToken": null,
  "groups": {
    "href": "https://api.stormpath.com/v1/accounts/ZugcG3JHQFOTKGEXAMPLE/groups"
  },
  "groupMemberships": {
    "href": "https://api.stormpath.com/v1/accounts/ZugcG3JHQFOTKGEXAMPLE/groupMemberships"
  },
  "directory": {
    "href": "https://api.stormpath.com/v1/directories/S2HZc7gXTumVYEXAMPLE"
  },
  "tenant": {
    "href": "https://api.stormpath.com/v1/tenants/wGbGaSNuTUix9EXAMPLE"
  },
}

When encountering a link object, you can use the link href attribute to interact with that resource as necessary.

Link Expansion

When requesting a resource you might want the Stormpath API server to return not only that resource, but also one or more of its linked resources. Link expansion allows you to retrieve related resources in a single request to the server instead of having to issue multiple separate requests.

Expand Query Parameter

For example, to retrieve an account and its parent directory, instead of issuing two requests (one for the account and another for its directory) add an expand query parameter with a value of directory to the resource URI.

For example:

curl -u $API_KEY_ID:$API_KEY_SECRET \
     -H "Accept: application/json" \
     "https://api.stormpath.com/v1/accounts/$ACCOUNT_ID?expand=directory"

Response:

{
    "href": "https://api.stormpath.com/v1/accounts/ZugcG3JHQFOTKGEXAMPLE",
    "username": "lonestarr",
    "email": "[email protected]",
    "fullName": "Lonestarr Schwartz",
    "givenName": "Lonestarr",
    "middleName": "",
    "surname": "Schwartz",
    "status": "ENABLED",
    "emailVerificationToken": null,
    "groups": {
        "href": "https://api.stormpath.com/v1/accounts/ZugcG3JHQFOTKGEXAMPLE/groups"
    },
    "groupMemberships": {
        "href": "https://api.stormpath.com/v1/accounts/ZugcG3JHQFOTKGEXAMPLE/groupMemberships"
    },
    "directory": {
        "href": "https://api.stormpath.com/v1/directories/S2HZc7gXTumVYEXAMPLE",
        "name": "Spaceballs",
        "description": "",
        "status": "ENABLED",
        "accounts": {
            "href":"https://api.stormpath.com/v1/directories/S2HZc7gXTumVYEXAMPLE/accounts"
        },
        "groups": {
            "href":"https://api.stormpath.com/v1/directories/S2HZc7gXTumVYEXAMPLE/groups"
        },
        "tenant":{
            "href":"https://api.stormpath.com/v1/tenants/wGbGaSNuTUix9EXAMPLE"
        }
    },
    "tenant": {
        "href": "https://api.stormpath.com/v1/tenants/wGbGaSNuTUix9EXAMPLE"
    }
}

Notice that the account’s directory attribute is no longer a link; it has been expanded in-line and included in the response body.

You can use this technique to reduce the number of round-trip communication requests to Stormpath API server, enhancing the performance of your application.

Expandable Attributes

Most link attributes are expandable. Check the resource’s specific documentation to see which of its link attributes are expandable.

Expansion Depth Limit

It is currently only possible to expand a resource’s immediate links. It is not currently possible to expand links of links.

For example, it would not be possible to return an account with its directory expanded and also the directory’s groups expanded as well. Link expansion is currently only possible one level ‘deep’.

If you have a critical need of multi-depth expansion, please contact us at support@stormpath.com and submit a feature request.

Expanding Multiple Links

You can specify more than one link attribute by specifying a comma-delimited list of attribute names to expand.

For example, to expand the example account’s directory and tenant links, execute the following GET request:

curl -u $API_KEY_ID:$API_KEY_SECRET \
     -H "Accept: application/json" \
     "https://api.stormpath.com/v1/accounts/$ACCOUNT_ID?expand=directory,tenant"

Expanding Collection Links

It is possible to expand links to Collection Resources as well. You can additionally provide pagination parameters to control the paged output of the expanded collection.

For example, to expand the above account’s groups (starting at the first group – index 0) and limiting to 10 results total, you can specify the groups attribute name followed offset and/or limit parameters enclosed in parenthesis. For example:

curl -u $API_KEY_ID:$API_KEY_SECRET \
     -H "Accept: application/json" \
     "https://api.stormpath.com/v1/accounts/$ACCOUNT_ID?expand=groups(offset:0,limit:10)"

The offset and limit values are enclosed in parenthesis and delimited by the colon : character.

If you specify parenthesis for a collection expansion, you must specify an offset value or a limit value or both. Parenthesis without an offset or limit is a query syntax error and should be fixed. For example, ?expand=groups() is invalid and should be changed to only ?expand=groups.

If you expand a Collection Resource and you do not specify parenthesis with an offset or limit (for example ?expand=groups), the default pagination values are used automatically.

Expansion Combinations

Finally, it should be noted that you can expand both standard (non-collection) links and collection links in the same expand directive. For example:

curl -u $API_KEY_ID:$API_KEY_SECRET \
     -H "Accept: application/json" \
     "https://api.stormpath.com/v1/accounts/$ACCOUNT_ID?expand=directory,groups(offset:0,limit:10)"

You can combine the two techniques to more precisely customize your desired output.


Tenants

Stormpath is a multi-tenant software service. When you sign up for Stormpath, a private data ‘space’ is created for you. This space is represented as a Tenant resource in the Stormpath REST API.

It might help to think of a Tenant as a Stormpath customer. As a Stormpath Tenant (customer), you own your Tenant resource and everything in it – Applications, Directories, Accounts, Groups, and so on.

In the Stormpath REST API specifically, your Tenant resource can be thought of as your global starting point. You can access everything in your tenant space by accessing your tenant resource first and then interacting with its other linked resources (applications collection, directories collection, etc).

Tenant Resource

Resource URI

/v1/tenants/:tenantId

Tenant Resource Attributes

Attribute Description Type Valid Value
href The tenant resource’s fully qualified URL. String
name The name of the tenant. Unique across all tenants. String 1 < N <= 255 characters
key Human readable tenant key. Unique across all tenants. String 1 < N <= 63 characters, no whitespace, lower-case a-z and dash ‘–’ characters only, cannot start or end with a dash ‘–’ character.
applications A link to the tenant’s applications. link
directories A link to the tenant’s directories. link

For Tenants, you can:

“Create” and “Delete” Tenant operations are currently not supported via the REST API. If you require this functionality, please email support@stormpath.com and request it.

Retrieve a Tenant

Execute a GET request with the tenant URI to retrieve the Tenant resource. You may only retrieve your own Tenant: every API Key that executes REST requests is associated with a Tenant, and the request caller may only retrieve the Tenant corresponding to the API Key used.

If you do not have your Tenant’s specific URI handy, you can always retrieve your Tenant using the current Tenant alias URI.

Example Request

curl -u $API_KEY_ID:$API_KEY_SECRET \
     -H "Accept: application/json" \
     "https://api.stormpath.com/v1/tenants/$TENANT_ID"

Example Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8;

{
  "href": "https://api.stormpath.com/v1/tenants/cJoiwcorTTmkDDBsf02AbA",
  "name": "My Tenant",
  "key": "myTenant",
  "applications": {
    "href": "https://api.stormpath.com/v1/tenants/cJoiwcorTTmkDDBsf02AbA/applications"
  },
  "directories": {
    "href": "https://api.stormpath.com/v1/tenants/cJoiwcorTTmkDDBsf02AbA/directories"
  }
}

Retrieve the Current Tenant

Because a REST caller can retrieve one and only one Tenant resource, it is often more convenient not to be concerned with the Tenant-specific URL is when performing a request, and instead use a simpler permanent alias.

You can request the current Tenant resource, and the API server will automatically issue a 302 redirect to the Tenant resource corresponding to the currently executing API caller. In other words, this endpoint redirects the API caller to their own Tenant’s URI.

Example Request

curl -u $API_KEY_ID:$API_KEY_SECRET -H "Accept: application/json" -L https://api.stormpath.com/v1/tenants/current

Example Response

HTTP/1.1 302 Moved Temporarily
Location: https://api.stormpath.com/v1/tenants/cJoiwcorTTmkDExaMpLe
Expires: 0
Cache-Control: no-cache, no-store, must-revalidate, max-age=0, proxy-revalidate, no-transform
Pragma: no-cache

Most REST libraries and web browsers will automatically issue a request for the resource in the Location header. If you do not see this, just execute a GET request to that Location and you will see your Tenant resource.

Tenant Applications

A Tenant has one or more Applications registered with Stormpath. Each registered application may communicate with Stormpath to simplify and automate its user management and authentication needs.

Tenant Applications Collection Resource URI

/v1/tenants/:tenantId/applications

List Tenant Applications

You can list your tenant’s applications by sending a GET request to your tenant’s applications Collection Resource href URL. The response is a paginated list of tenant applications.

You may also use collection pagination and sort ordering query parameters to customize the paginated response.

Example Request

curl -u $API_KEY_ID:$API_KEY_SECRET \
     -H "Accept: application/json" \
     "https://api.stormpath.com/v1/tenants/$TENANT_ID/applications"

Example Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
  "href": "https://api.stormpath.com/v1/tenants/cJoiwcorTTmkDDBsf02AbA/applications",
  "offset": 0,
  "limit": 25,
  "items" : [
    {
      "href" : "https://api.stormpath.com/v1/applications/WpM9nyZ2TbaEzfbRvLk9KA"
      ... remaining Application name/value pairs ...
    },
    {
      "href" : "https://api.stormpath.com/v1/applications/aLlyOUrBAse34js9hjiH9j"
      ... remaining Application name/value pairs ...
    },
    {
      "href" : "https://api.stormpath.com/v1/applications/Xhf0a9HLA02djsdP90dsQ2"
      ... remaining Application name/value pairs ...
    },
  ]
}

Search Tenant Applications

You may search for applications by sending a GET request to your tenant’s applications Collection Resource href URL using search query parameters. Any matching applications within your tenant will be returned as a paginated list.

Searchable Application Attributes

The following application attributes are searchable via filter and attribute searches:

  • name
  • description
  • status

In addition to the the search query parameters, you may also use pagination and sorting query parameters to customize the paginated response. For example:

curl -u $API_KEY_ID:$API_KEY_SECRET \
     -H "Accept: application/json" \
     "https://api.stormpath.com/v1/tenants/$TENANT_ID/applications?q=foo&orderBy=name&offset=0&limit=50"

Working With Tenant Applications

Application resources supports the full suite of CRUD commands and other interactions. Please see the Applications section for more information.

Tenant Directories

A Tenant has one or more Directories that contain accounts and groups. Accounts may login to applications and groups can be used for access control within applications.

Tenant Directories Collection Resource URI

/v1/tenants/:tenantId/directories

List Tenant Directories

You can list your tenant’s directories by sending a GET request your tenant’s directories Collection Resource href URL. The response is a paginated list of your tenant’s directories.

You may also use collection pagination and sort ordering query parameters to customize the paginated response.

Example request

curl -u $API_KEY_ID:$API_KEY_SECRET \
     -H "Accept: application/json" \
     "https://api.stormpath.com/v1/tenants/$TENANT_ID/directories"

Example Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8;

{
  "href": "https://api.stormpath.com/v1/tenants/Gh9238fksJlsieJkPkQuW/directories"
  "offset": 0,
  "limit": 25,
  "items" : [
    {
      "href" : "https://api.stormpath.com/v1/directories/bckhcGMXQDujIXpbCDRb2Q"
      ... remaining Directory name/value pairs ...
    },
    {
      "href" : "https://api.stormpath.com/v1/directories/lIKeabOss8w9fJf0fJfb34"
      ... remaining Directory name/value pairs ...
    },
    {
      "href" : "https://api.stormpath.com/v1/directories/Hfjks7kj9sfKfh9fhsPifa"
      ... remaining Directory name/value pairs ...
    }
  ]
}

Search Tenant Directories

You may search for directories by sending a GET request to your tenant’s directories Collection Resource href URL using search query parameters. Any matching directories with your tenant will be returned as a paginated list.

Searchable Directory Attributes

The following directory attributes are searchable via filter and attribute searches:

  • name
  • description
  • status

In addition to the the search query parameters, you may also use pagination and sorting query parameters to customize the paginated response. For example:

curl -u $API_KEY_ID:$API_KEY_SECRET \
     -H "Accept: application/json" \
     "https://api.stormpath.com/v1/tenants/$TENANT_ID/directories?q=foo&orderBy=name&offset=0&limit=50"

Working With Tenant Directories

Directory resources support the full suite of CRUD commands and other interactions. Please see the Directories section for more information.


Applications

An Application in Stormpath represents any real world piece of software that communicates with Stormpath to offload its user management and authentication needs. The application can be anything that can make a REST API call – a web application that you are writing, a web server like Apache or Nginx, a Linux operating system, etc – basically anything that a user can login to. A tenant administrator can register one or more applications with Stormpath.

You control who may login to an application by assigning (or ‘mapping’) one or more Directories or Groups (generically called account stores) to an application. The Accounts in these associated directories or groups (again, account stores) collectively form the application’s user base. These accounts are considered the application’s users and they can login to the application. Therefore, you can control user population that may login to an application by managing which account stores are assigned to the application.

Even the Stormpath Admin Console and API is represented as an Application (named Stormpath), so you can control who has administrative access to your Stormpath tenant by managing the Stormpath application’s associated account stores.

Application Resource

An individual Application resource may be accessed via its Resource URI:

Resource URI

/v1/applications/:applicationId

Resource Attributes

Attribute Description Type Valid Value
href The application’s fully qualified URL. String
name The name of the application. Must be unique across all applications within a tenant. String 1 <= N <= 255 characters. Unique within a tenant
description A description of the application. For example, providing the application’s homepage URL might be helpful. String 0 <= N <= 4000 chars
status enabled applications allow accounts to login. disabled applications prevent accounts from logging in. Newly created applications are enabled by default. enum enabled, disabled
tenant A link to the tenant that owns the application. link
passwordResetTokens A link to the application’s password reset tokens collection, used in password reset workflows. link
loginAttempts A link to to the application’s login attempts collection. When an account attempts to login to an application, the login attempt is submitted to this linked resource. link
accounts A link to all accounts that may login to the application. This is an aggregate view of all accounts in the application’s assigned account stores. link
groups A link to all groups that are accessible to the application for authorization (access control) needs. This is an aggregate view of all groups in the application’s assigned account stores. link
accountStoreMappings A link to the collection of all account store mappings that represent the application. The accounts and groups within the mapped account stores are obtainable by the accounts and groups links respectively. link
defaultAccountStoreMapping A link to the account store mapping that reflects the default account store where the application will store newly created accounts. (A POST to /v1/applications/:applicationId/accounts will result in storing the new account in the default account store). A null value disables the application from directly creating new accounts. link null or link
defaultGroupStoreMapping A link to the account store mapping that reflects the default group store where the application will store newly created groups. (A POST to /v1/applications/:applicationId/groups will result in storing the new group in the default group store). A null value disables the application from directly creating new groups. link null or link

For Applications, you can:

Locate an Application’s REST URL

When communicating with the Stormpath REST API, you might need to reference an application using its REST URL or href.

In order to locate an application’s href, you’ll need to first search for the tenant for the specific application using some information that you have available.

For example, if you want to find the href for an application named “My Application”, you’ll need to search the tenant for the “My Application” application resource:

Example Request

curl -u $API_KEY_ID:$API_KEY_SECRET \
     -H "Accept: application/json" \
     "https://api.stormpath.com/v1/tenants/23mq7BPIxNgPUPZDwj04SZ/applications?name=My%20Application"

Example Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
    "href": "https://api.stormpath.com/v1/tenants/23mq7BPIxNgPUPZDwj04SZ/applications",
    "offset": 0,
    "limit": 25,
    "items": [
      {
        "href": "https://api.stormpath.com/v1/applications/3hFENJHLaH1Vy4GSbscrtv",
        "name": "My Application"
        /* remaining Application name/value pairs */
      }
    ]
}

If you know the name exactly, you can use an attribute search (e.g., name=) or, if you only know a small part, you can use a filter search (e.g., q=My) to narrow the results.

Create an Application (aka Register an Application with Stormpath)

For an application to communicate with Stormpath, you must first register it with Stormpath.

You register an application with Stormpath by simply creating a new application resource. This is performed by submitting an HTTP POST request to the /v1/applications endpoint. This will create a new Application instance within the caller’s tenant.

When you submit the POST, at least the name attribute must be specified, and it must be unique compared to all other applications in your tenant. The description and status attribute are optional.

Required Attribute

  • name – must be unique compared to all other applications in your tenant.

Optional Attributes

Example Request

POST https://api.stormpath.com/v1/applications
Content-Type: application/json;charset=UTF-8

{
  "name": "Best application ever",
  "description": "Really. The best application ever.",
  "status": "enabled"
}

Example Response

HTTP/1.1 201 Created
Location: https://api.stormpath.com/v1/applications/WpM9nyZ2TbaEzfbRvLk9KA
Content-Type: application/json;charset=UTF-8;

{
  "href": "https://api.stormpath.com/v1/applications/WpM9nyZ2TbaEzfbRvLk9KA",
  "name": "Best application ever",
  "description": "Really. The best application ever.",
  "status": "ENABLED",
  "tenant": {
    "href": "https://api.stormpath.com/v1/tenants/cJoiwcorTTmkDDBsf02AbA"
  },
  "accounts": {
    "href": "https://api.stormpath.com/v1/applications/WpM9nyZ2TbaEzfbRvLk9KA/accounts"
  },
  "groups": {
    "href": "https://api.stormpath.com/v1/applications/WpM9nyZ2TbaEzfbRvLk9KA/groups"
  },
  "passwordResetTokens" : {
    "href" : "http://api.stormpath.com/v1/applications/WpM9nyZ2TbaEzfbRvLk9KA/passwordResetTokens"
  }
}

You may use the response’s Location header or the top-level href attribute to further interact with your new application resource.

By default, no accounts may login to a newly created application, and the new application cannot create accounts or groups immediately. Applications must first be associated with one or more account stores to enable this behavior.

Account store association however is mostly used for more complex applications. If you want to create an application quickly and enable this additional behavior immediately, use the createDirectory query parameter as discussed next.

Create an Application and Directory

The above Create Application POST request assumes you will later assign account stores to the application so accounts may log in to the application. This means that, by default, no one can login to a newly created application, nor can the application create new accounts or new groups directly. For this additional functionality, one or more account stores must be associated with the application.

For many use cases, that is unnecessary work. If you want to associate the Application with a new Directory automatically so you can start creating accounts and groups for the application immediately (without having to map other account stores, you can use the createDirectory query parameter.

Automatically creating a directory when creating an application does not make that Directory private or restrict usage to only that Application. The created directory is no different than any other directory. The createDirectory query parameter exists as a convenience to reduce the number of steps you would have had to execute otherwise.

If you delete an application, you must manually delete any auto-created directory yourself. There is no shortcut to delete an auto-created directory. This is to ensure safety in case the directory might be used by other applications.

createDirectory=true

When sending the POST request, you can append a createDirectory=true query parameter name/value pair to the POST URL:

POST https://api.stormpath.com/v1/applications?createDirectory=true
Content-Type: application/json;charset=UTF-8

{
    "name": "My new app"
}

This request will:

  1. Create the application.
  2. Create a brand new Directory and automatically name the directory based on the application. The generated name will reflect the new application’s name as best as is possible, guaranteeing that it is unique compared to any of your existing directories.
  3. Set the new Directory as the application’s initial account store.
  4. Enable the new Directory as the application’s default account store, ensuring any new accounts created directly by the application are stored in the new Directory.
  5. Enable the new Directory as the application’s default group store, ensuring any new groups created directly by the application are stored in the new Directory.

This allows you to create accounts and groups directly via the application’s /accounts and /groups endpoints respectively immediately, without having to go through an account store mapping exercise.

createDirectory=a+custom+name

If you want to automatically create a Directory for your application, and you also want to manually specify the new Directory’s name, instead of using a true value as the query parameter value, you can specify a String name instead:

POST https://api.stormpath.com/v1/applications?createDirectory=My+App+Directory
Content-Type: application/json;charset=UTF-8

{
    "name": "My new app"
}

this request will:

  1. Create the application.
  2. Create a brand new Directory and automatically set the Directory’s name to be your specified text value (e.g. ‘My App Directory’ in the example above). HOWEVER: If the directory name you choose is already in use by another of your existing directories, the request will fail. You will either need to choose a different directory name or specify true and let Stormpath generate an unused unique name for you.
  3. Set the new Directory as the application’s initial account store.
  4. Enable the new Directory as the application’s default account store, ensuring any new accounts created directly by the application are stored in the new Directory.
  5. Enable the new Directory as the application’s default group store, ensuring any new groups created directly by the application are stored in the new Directory.

Retrieve an Application

After you have created an application, you may retrieve its contents by sending a GET request to the application’s URL returned in the Location header or href attribute.

If you don’t have the application’s URL, you can find it by looking it up in the Stormpath Admin Console or by searching your tenant’s applications for the application and then using its href.

Example Request

GET https://api.stormpath.com/v1/applications/WpM9nyZ2TbaEzfbRvLk9KA

Example Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8;

{
  "href": "https://api.stormpath.com/v1/applications/WpM9nyZ2TbaEzfbRvLk9KA",
  "name": "Best application ever",
  "description": "Really. The best application ever.",
  "status": "ENABLED",
  "tenant": {
    "href": "https://api.stormpath.com/v1/tenants/cJoiwcorTTmkDDBsf02AbA"
  },
  "accounts": {
    "href": "https://api.stormpath.com/v1/applications/WpM9nyZ2TbaEzfbRvLk9KA/accounts"
  },
  "groups": {
    "href": "https://api.stormpath.com/v1/applications/WpM9nyZ2TbaEzfbRvLk9KA/groups"
  },
  "passwordResetTokens" : {
    "href" : "http://api.stormpath.com/v1/applications/WpM9nyZ2TbaEzfbRvLk9KA/passwordResetTokens"
  }
}

Expandable Resources

When retrieving an application, you can also retrieve one or more of its linked resources by expanding them in-line using the expand query parameter.

The following Application attributes are expandable:

  • tenant
  • accounts
  • groups

Also, because accounts and groups are Collection Resources themselves, you can additionally control pagination for either expanded collection. For example:

GET https://api.stormpath.com/v1/applications/WpM9nyZ2TbaEzfbRvLk9KA?expand=tenant,accounts(offset:0,limit:50)

See the Link Expansion section for more information on expanding link attributes.

Update an Application

Submit an HTTP POST to an application’s href when you want to change one or more specific application attributes. Unspecified attributes are not changed, but at least one attribute must be specified.

Updatable Application Attributes

Example Request

POST https://api.stormpath.com/v1/applications/WpM9nyZ2TbaEzfbRvLk9KA
Content-Type: application/json;charset=UTF-8

{
  "description": "A new description."
}

Example Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8;

{
  "href": "https://api.stormpath.com/v1/applications/WpM9nyZ2TbaEzfbRvLk9KA",
  "name": "Best application ever",
  "description": "A new description.",
  "status": "enabled",
  "tenant": {
    "href": "https://api.stormpath.com/v1/tenants/cJoiwcorTTmkDDBsf02AbA"
  },
  "accounts": {
    "href": "https://api.stormpath.com/v1/applications/WpM9nyZ2TbaEzfbRvLk9KA/accounts"
  },
  "groups": {
    "href": "https://api.stormpath.com/v1/applications/WpM9nyZ2TbaEzfbRvLk9KA/groups"
  },
  "passwordResetTokens" : {
    "href" : "http://api.stormpath.com/v1/applications/WpM9nyZ2TbaEzfbRvLk9KA/passwordResetTokens"
  }
}

Enable an Application

Enabled applications allow associated accounts to login. Disabled applications prevent logins. When you create an application, it is enabled by default.

You can enable an application (and thereby allow associated accounts to login) by setting the status attribute to equal ENABLED. For example:

Example Request

POST https://api.stormpath.com/v1/applications/WpM9nyZ2TbaEzfbRvLk9KA
Content-Type: application/json;charset=UTF-8

{
  "status": "ENABLED"
}

Example Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8;

{
  "href": "https://api.stormpath.com/v1/applications/WpM9nyZ2TbaEzfbRvLk9KA",
  "name": "Best application ever",
  "description": "A new description.",
  "status": "ENABLED",
  "tenant": {
    "href": "https://api.stormpath.com/v1/tenants/cJoiwcorTTmkDDBsf02AbA"
  },
  "accounts": {
    "href": "https://api.stormpath.com/v1/applications/WpM9nyZ2TbaEzfbRvLk9KA/accounts"
  },
  "groups": {
    "href": "https://api.stormpath.com/v1/applications/WpM9nyZ2TbaEzfbRvLk9KA/groups"
  },
  "passwordResetTokens": {
    "href": "https://api.stormpath.com/v1/applications/WpM9nyZ2TbaEzfbRvLk9KA/passwordResetTokens"
  }
}

Disable an Application

Disabled applications prevent associated accounts from logging in. When you create an application, it is enabled by default.

If you want to prevent logins for an application – for example, maybe you are undergoing maintenance and don’t want accounts to login during this time – you can disable the application.

You can disable an application (and thereby prevent associated accounts from logging in) by setting the status attribute to equal DISABLED. For example:

Example Request

POST https://api.stormpath.com/v1/applications/WpM9nyZ2TbaEzfbRvLk9KA
Content-Type: application/json;charset=UTF-8

{
  "status": "DISABLED"
}

Example Response

HTTP/1.1 200 OK
 Content-Type: application/json;charset=UTF-8;

 {
   "href": "https://api.stormpath.com/v1/applications/WpM9nyZ2TbaEzfbRvLk9KA",
   "name": "Best application ever",
   "description": "A new description.",
   "status": "DISABLED",
   "tenant": {
     "href": "https://api.stormpath.com/v1/tenants/cJoiwcorTTmkDDBsf02AbA"
   },
   "accounts": {
     "href": "https://api.stormpath.com/v1/applications/WpM9nyZ2TbaEzfbRvLk9KA/accounts"
   },
   "groups": {
     "href": "https://api.stormpath.com/v1/applications/WpM9nyZ2TbaEzfbRvLk9KA/groups"
   },
   "passwordResetTokens": {
     "href": "https://api.stormpath.com/v1/applications/WpM9nyZ2TbaEzfbRvLk9KA/passwordResetTokens"
   }
 }

Delete an Application

You can delete an application (‘unregister it’) by sending an HTTP DELETE request to the application’s href URL.

Deleting an application completely erases the application and any of its related data from Stormpath.

We recommend that you disable an application instead of deleting it if you anticipate that you might use the application again or if you want to retain its data for historical reference.

If you wish to delete an application:

Example Request

DELETE https://api.stormpath.com/v1/applications/WpM9nyZ2TbaEzfbRvLk9KA

Example Response

HTTP/1.1 204 No Content

The Stormpath console application cannot be deleted.

List Applications

You may list your tenant’s applications as described in List Tenant Applications.

Search Applications

You may search for applications as described in Search Tenant Applications.

Application Accounts

An application’s accounts collection is the collection of all accounts that are accessible to the application.

It might sound a little odd to phrase it that way (accessible to), but it makes sense when you realize that applications do not have direct accounts of their own. Accounts are ‘owned’ by directories and instead made available to applications.

This means that an application’s accounts collection is virtual. This virtual collection is an aggregate ‘view’ of all accounts that are:

  1. in any directory assigned to the application
  2. in any group directly assigned to the application

This is a powerful and convenient feature: as you add or remove account stores from an application to control its user population, you automatically ‘bring in’ any of their accounts. You can interact with the application’s accounts collection, like search for accounts or add new accounts, like you would a normal collection.

Most application developers do not need to be aware that an application’s accounts collection is virtual. The most common case in Stormpath for simpler apps is to just create an application with its own directory for its own needs. Used this way, the application’s and the directory’s accounts (and groups) are the same.

But it is nice to know that you can customize the application’s account population with other directories or groups in the future if you need to do so.

Application Accounts Collection Resource URI

/v1/applications/:applicationId/accounts

Applications additionally support the following account-specific functionality:

Register a New Application Account

If your application wants to register a new account, you create a new account resource on the application’s accounts endpoint.

POST the account resource attributes required and any additional ones you desire.

Example Request

curl -X POST --user $YOUR_API_KEY_ID:$YOUR_API_KEY_SECRET \
     -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -d '{
         "username" : "jlpicard",
         "email" : "[email protected]",
         "givenName" : "Jean-Luc",
         "middleName" : "",
         "surname" : "Picard",
         "password" : "uGhd%a8Kl!"
         "status" : "ENABLED",
     }' \
 "https://api.stormpath.com/v1/applications/WpM9nyZ2TbaEzfbRvLk9KA/accounts"

The response will contain the newly saved resource:

Example Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8;

{
  "href" : "https://api.stormpath.com/v1/accounts/cJoiwcorTTmkDDBsf02AbA",
  "username" : "jlpicard",
  "email" : "[email protected]",
  "fullName" : "Jean-Luc Picard",
  "givenName" : "Jean-Luc",
  "middleName" : "",
  "surname" : "Picard",
  "status" : "ENABLED",
  "customData": {
    "href": "https://api.stormpath.com/v1/accounts/cJoiwcorTTmkDDBsf02AbA/customData"
  },
  "groups" : {
    "href" : "https://api.stormpath.com/v1/accounts/cJoiwcorTTmkDDBsf02AbA/groups"
  },
  "groupMemberships" : {
    "href" : "https://api.stormpath.com/v1/accounts/cJoiwcorTTmkDDBsf02AbA/groupMemberships"
  },
  "directory" : {
    "href" : "https://api.stormpath.com/v1/directories/1FaQ6kZxTL4DVJXWeXtUh7"
  },
  "tenant" : {
    "href" : "https://api.stormpath.com/v1/tenants/Ad8mIcavSty7XzD-xZdP3g"
  },
  "emailVerificationToken" : null
}

How does this work?

As we said previously, an Application does not ‘own’ accounts of its own – it has access to accounts in one or more directories or groups and the directories actually own the accounts. So how are we able to create a new account based on only the application?

The v1/applications/:applicationId/accounts URI is a convenience: when you POST a new account resource, Stormpath will automatically route that creation request to a designated directory or group assigned to the Application. The account is then persisted in that directory or group and then made immediately available to the application.

Stormpath uses a generic term, Account Store, to generically refer to either a directory or a group since they are both containers for (store) accounts.

For most applications that have only a single assigned account store (again, a directory or group), the account is persisted in that account store immediately – the application developer does not even really need to know that Stormpath automates this.

However, applications that map more than one account store to define their account population have the option of specifying which of those mapped account stores should receive newly created accounts. You can choose a default account store. If you do not choose one, the first one in the list of mapped account stores is the default location to store new accounts. We’ll talk about setting the default account store and managing an application’s assigned account stores later in Application Account Store Mappings.

Register a New Application Account with your own Custom Data

When you create an application account, in addition to Stormpath’s account attributes, you may also specify your own custom data by including a customData JSON object:

curl -X POST --user $YOUR_API_KEY_ID:$YOUR_API_KEY_SECRET \
     -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -d '{
             "username" : "jlpicard",
             "email" : "[email protected]",
             "givenName" : "Jean-Luc",
             "middleName" : "",
             "surname" : "Picard",
             "password" : "uGhd%a8Kl!"
             "status" : "ENABLED",
             "customData": {
                 "rank": "Captain",
                 "birthDate": "2305-07-13",
                 "birthPlace": "La Barre, France",
                 "favoriteDrink": "Earl Grey tea"
             }
         }' \
     "https://api.stormpath.com/v1/applications/WpM9nyZ2TbaEzfbRvLk9KA/accounts"

Once created, you can further modify the custom data – delete it, add and remove attributes, etc as necessary. See the custom data section for more information and customData requirements/restrictions.

Send a Welcome Email

Stormpath makes it easy to send a welcome email to the person associated with a newly created account.

When you create a new account resource, it is stored in a Directory. If the account is created in a directory with Account Registration enabled, Stormpath will automatically send the welcome email to the account’s email address on your behalf.

The email will be shown as coming from your email address, and you don’t have to worry about email servers or how to send the email yourself. You can customize the email template to say whatever you like.

By association then, if you add an account to your application programmatically or through the Stormpath Admin Console, and that account is stored in a directory with this feature enabled, Stormpath will send a welcome email to that account email address.

This workflow is disabled by default on Directories, but you can enable it easily in the Stormpath Admin Console UI. Refer to the Stormpath Admin Console product guide for complete instructions.

Verify An Account’s Email Address

This workflow allows you to send a welcome email to a newly registered account and optionally verify that they own the email addressed used during registration.

The email verification workflow involves changes to an account at an application level, and as such, this workflow relies on the account resource as a starting point. For more information on working with these workflows via REST after they have already been configured, refer to the Working With Accounts section of this guide. This workflow is disabled by default for accounts, but you can enable it easily in the Stormpath Admin Console UI. Refer to the Stormpath Admin Console product guide for complete instructions.

Workflows are only available on cloud directories and only configurable using the Stormpath Admin Console. They are not currently configurable via the REST API. Also, the Stormpath Administrator directory’s automated workflows cannot be altered.

Log In (Authenticate) an Account

You may authenticate an account by POSTing a loginAttempt resource to the application’s login attempts endpoint:

Application Login Attempt Collection Resource URI

/v1/applications/:applicationId/loginAttempts

Login Attempt Resource Attributes

Attribute Description Type Valid Value
type The type of the login attempt. The only currently supported type is basic. Additional types will likely be supported in the future. Enum basic
value The Base64 encoded username:plaintextPassword pair. For example, for username jsmith or email [email protected] and plaintext password mySecretPassword this value attribute would be set to the following computed result: base64_encode("jsmith:mySecretPassword");

The base64_encode method call is only an example. You will need to use the Base64 encoding method is available to you in your chosen programming language and/or software frameworks.
String Base64 encoded String
accountStore An optional link to the application’s accountStore (directory or group) that you are certain contains the account attempting to login.

Specifying this attribute can speed up logins if you know exactly which of the application’s assigned account stores contains the account: Stormpath will not have to iterate over the assigned account stores to find the account to authenticate it. This can speed up logins significantly if you have many account stores (> 15) assigned to the application.

This is an optional attribute.
link

Execute Account Login Attempt (HTTP POST)

An HTTP POST authenticates an associated application account. Only HTTP POST is supported.

The POST body must be a JSON object with the Login Attempt Resource Attributes (type and value).

The type attribute must equal basic. You compute the value using the following (pseudo code) logic:

String concatenated = username_or_email + ':' + plain_text_password
byte[] bytes = concatenated.to_byte_array()
String value = base64_encode( bytes )

For example, if the username is jsmith and the password is changeme, you can compute the value using OpenSSL:

$ echo -n "jsmith:changeme" | openssl enc -base64
anNtaXRoOmNoYW5nZW1l

Place the result in the request body as the value JSON attribute, for example:

Example Request

curl -X POST --user $YOUR_API_KEY_ID:$YOUR_API_KEY_SECRET \
 -H "Accept: application/json" \
 -H "Content-Type: application/json" \
 -d '{
       "type": "basic",
       "value": "anNtaXRoOmNoYW5nZW1l"
     }' \
 "https://api.stormpath.com/v1/applications/$YOUR_APPLICATION_ID/loginAttempts"

If the login attempt is successful, a 200 OK response is returned with a link to the successfully authenticated account:

Example Login Attempt Success Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8;

{
  "account": {
    "href" : "https://api.stormpath.com/v1/accounts/5BedLIvyfLjdKKEEXAMPLE"
  }
}

If the login attempt fails, a 400 Bad Request is returned with an error payload explaining why the attempt failed:

Example Login Attempt Failure Response

HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8;

{
  "status": 400,
  "code": 400,
  "message": "Invalid username or password.",
  "developerMessage": "Invalid username or password.",
  "moreInfo": "mailto:[email protected]"
}

If you desire to target a specific accountStore, then include the reference in the request. For example:

Example Request with AccountStore

curl -X POST --user $YOUR_API_KEY_ID:$YOUR_API_KEY_SECRET \
 -H "Accept: application/json" \
 -H "Content-Type: application/json" \
 -d '{
       "type": "basic",
       "value": "anNtaXRoOmNoYW5nZW1l"
       "accountStore": {
             "href": "https://api.stormpath.com/v1/groups/$YOUR_GROUP_ID"
       }
     }' \
 "https://api.stormpath.com/v1/applications/$YOUR_APPLICATION_ID/loginAttempts"

If the login attempt is successful, a 200 OK response is returned with a link to the successfully authenticated account:

Example Login Attempt with AccountStore Success Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8;

{
  "account": {
    "href" : "https://api.stormpath.com/v1/accounts/5BedLIvyfLjdKKEEXAMPLE"
  }
}

If the login attempt fails, a 400 Bad Request is returned with an error payload explaining why the attempt failed:

Example Login Attempt with AccountStore Failure Response

HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8;

{
  "status" : 400,
  "code" : 5114,
  "message" : "Oops! We encountered an unexpected error.  Please contact support and explain what you were doing at the time this error occurred.",
  "developerMessage" : "The specified application account store reference is invalid: the specified account store is not one of the application's assigned account stores.  Targeted authentication attempts must target one of the application's existing assigned account stores.",
  "moreInfo" : "https://www.stormpath.com/docs/errors/5114"
}

If you want the actual account object returned from a successful authentication attempt, then you can expand the account in-line using the expand query parameter. For example:

Example Request with Account Expansion

curl -X POST --user $YOUR_API_KEY_ID:$YOUR_API_KEY_SECRET \
 -H "Accept: application/json" \
 -H "Content-Type: application/json" \
 -d '{
       "type": "basic",
       "value": "anNtaXRoOmNoYW5nZW1l"
     }' \
 "https://api.stormpath.com/v1/applications/$YOUR_APPLICATION_ID/loginAttempts?expand=account"

If the login attempt is successful, a 200 OK response is returned with the successfully authenticated account:

Example Response with Account Expansion

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8;

{
  "href" : "https://api.stormpath.com/v1/accounts/cJoiwcorTTmkDDBsf02AbA",
  "username" : "jsmith",
  "email" : "[email protected]",
  "fullName" : "John Smith",
  "givenName" : "John",
  "middleName" : "",
  "surname" : "Smith",
  "status" : "ENABLED",
  "customData": {
    "href": "https://api.stormpath.com/v1/accounts/cJoiwcorTTmkDDBsf02AbA/customData"
  },
  "groups" : {
    "href" : "https://api.stormpath.com/v1/accounts/cJoiwcorTTmkDDBsf02AbA/groups"
  },
  "groupMemberships" : {
    "href" : "https://api.stormpath.com/v1/accounts/cJoiwcorTTmkDDBsf02AbA/groupMemberships"
  },
  "directory" : {
    "href" : "https://api.stormpath.com/v1/directories/1FaQ6kZxTL4DVJXWeXtUh7"
  },
  "tenant" : {
    "href" : "https://api.stormpath.com/v1/tenants/Ad8mIcavSty7XzD-xZdP3g"
  },
  "emailVerificationToken" : null
}

Reset An Account’s Password

Stormpath has a comprehensive mechanism for secure password reset, as well.

Understanding The Password Reset Workflow

In Stormpath, the model used for password reset is based the common standard of sending an email to the address associated with the account. This email contains a verification link with a limited-life token. The end-user clicks this link and is redirected to either your own or a Strompath-owned password reset page where he or she can enter a new password.

At no point is the user shown, or does Stormpath have access to, the original password once it has been hashed during account creation. The only ways to change an account password through Stormpath once an account has been created are to allow the user to update it (without seeing the original value) after being authenticated or to use the password reset workflow.

The Password Reset Base URL

It is expected that the directory’s Password Reset workflow’s Password Reset Base URL has been set to a URL that will be processed by your own application web server. This URL should be free of any query parameters, as the Stormpath back-end will append on to the URL a parameter used to verify the email. If this URL is not set, a default Stormpath-branded page will appear which allows the user to complete the workflow.

The Account Verification Base URL defaults to a Stormpath API Sever URL which, while it is functional, is a Stormpath API server web page. Because it will likely confuse your application end-users if they see a Stormpath web page, we strongly recommended that you specify a URL that points to your web application. Moreover, when specifying the Base URL, ensure it is a Base URL without query parameters

Trigger The Password Reset Email (Create A Token)

In order to reset an account’s password, you’ll need to create a passwordResetToken. In order to generate these tokens, you must retrieve an email address from the user and pass it along with the request.

Generating a passwordResetToken will inform Stormpath that you wish to initiate a password reset for a particular account. In addition, creating a new password reset token will automatically send a password reset email to the provided email address if and only if that address corresponds with an account listed in the application’s account stores.

The application password reset tokens endpoint supports the password reset workflow for an account in the application’s assigned account stores.

Password Reset Tokens Collection Resource URI

/v1/applications/:applicationId/passwordResetTokens

Resource Attributes

Attribute Description Type Valid Value
href Fully qualified URL of the password reset token resource. String
email Email address of the account for which the password reset will occur. String Valid email address. Required.
account A link to the account for which the password reset will occur. Link Cannot set in a request. Returned in a response only.

The application password reset tokens endpoint supports the password reset workflow for an account in the application assigned account stores.

A successful HTTP POST sends a password reset email to the first discovered account associated with the corresponding application. The email recipient can then click a password reset URL in the email to reset their password in a web form.

The POST body must be a JSON object with a single email attribute:

Example Request

POST https://api.stormpath.com/v1/applications/WpM9nyZ2TbaEzfbRvLk9KA/passwordResetTokens
Content-Type: application/json;charset=UTF-8

{
  "email": "[email protected]"
}

Example Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8;

{
  "href" : "https://api.stormpath.com/v1/applications/WpM9nyZ2TbaEzfbRvLk9KA/passwordResetTokens/j6HqguWPSBSXM2xmcOUShw"
  "email" : "[email protected]"
  "account" : {
    "href" : "https://api.stormpath.com/v1/accounts/cJoiwcorTTmkDDBsf02bAb"
  }
}

A 200 OK response indicates that a password reset email will be sent as soon as possible to the email specified.

If the password reset token creation fails, a 400 Bad Request is returned with an error payload explaining why the attempt failed:

Example Password Reset Token Creation Failure Response

HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8;

{
  status: 404,
  code: 404,
  message: "The requested resource does not exist.",
  developerMessage: "The requested resource does not exist.",
  moreInfo: "mailto:[email protected]"
}

At this point, an email will be built using the password reset base URL specified in the Stormpath Admin Console.

In a real-world implementation, you must build an end-point in your application that is designed to accept a request with the query string parameter “sptoken”, which is the token value generated for the user. This token is then used to verify the reset request before updating the account accordingly.

Validate A Password Reset Request (Validate A Token)

Once you’ve successfully generated a token for a password request, you’ll need to consume it to allow the user to change his or her password. To do this, Stormpath sends an email (that you can customize) to the user with a link and a verification token in the format that follows:

http://yoursite.com/path/to/reset/page?sptoken=$TOKEN

Once the user clicks this browser, your controller should retrieve the token from the query string and check it against the Stormpath API.

Retrieving a token resource successfully using an HTTP GET indicates that the token is valid. Thus, to validate a token, you call to the passwordResetTokens end point and specify the token captured from the query string as the specific resource to request:

Example GET Request

GET https://api.stormpath.com/v1/applications/WpM9nyZ2TbaEzfbRvLk9KA/passwordResetTokens/j6HqguWPSBSXM2xmcOUShw

Example Success Response (if token is valid)

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8;

{
  "href": "https://api.stormpath.com/v1/applications/WpM9nyZ2TbaEzfbRvLk9KA/passwordResetTokens/j6HqguWPSBSXM2xmcOUShw",
  "email": "[email protected]",
  "account": {
      "href": "https://api.stormpath.com/v1/accounts/cJoiwcorTTmkDDBsf02bAb"
  }
}

If the password reset token is invalid – it never existed or has expired – a 404 Not Found response is returned.

Example Error Response

 HTTP/1.1 404 Not Found
 Content-Type: application/json;charset=UTF-8;

   {
     "status": 404,
     "code": 404,
     "message": "The requested resource does not exist.",
     "developerMessage": "The requested resource does not exist.",
     "moreInfo": "mailto:[email protected]"
  }

After a successfully GET with the query string token, you can return a page to the end user to collect the password to update for the account. Once you have the password, you can update it by a POST to the password reset token’s endpoint. This is the same endpoint that you used to validate the token above.

Example POST Request

POST https://api.stormpath.com/v1/applications/WpM9nyZ2TbaEzfbRvLk9KA/passwordResetTokens/j6HqguWPSBSXM2xmcOUShw

{
  "password": "$PASSWORD_FROM_USER"
}

Example Success Response

HTTP/1.1 200 OK

{
    "account": {
        "href": "https://api.stormpath.com/v1/accounts/5F63i6mzwRsyymEsfUl7ql"
    }
}

On success, the response will include a link to the account that the password was reset on. This call on success will send the password change confirmation email that was configured in the Administrator Console to the email account associated with the account.

List Application Accounts

You can list your application’s accounts by sending a GET request to your application’s accounts Collection Resource href URL. The response is a paginated list of application accounts.

You may also use collection pagination and sort ordering query parameters to customize the paginated response.

Example Request

curl -u $API_KEY_ID:$API_KEY_SECRET \
     -H "Accept: application/json" \
     "https://api.stormpath.com/v1/applications/$APPLICATION_ID/accounts"

Example Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
  "href": "https://api.stormpath.com/v1/applications/cJoiwcorTTmkDDBsf02AbA/accounts",
  "offset": 0,
  "limit": 25,
  "items" : [
    {
      "href" : "https://api.stormpath.com/v1/accounts/WpM9nyZ2TbaEzfbRvLk9KA"
      ... remaining Account name/value pairs ...
    },
    {
      "href" : "https://api.stormpath.com/v1/accounts/aLlyOUrBAse34js9hjiH9j"
      ... remaining Account name/value pairs ...
    },
    {
      "href" : "https://api.stormpath.com/v1/accounts/Xhf0a9HLA02djsdP90dsQ2"
      ... remaining Account name/value pairs ...
    },
  ]
}

Search Application Accounts

You may search for directories by sending a GET request to your application’s accounts Collection Resource href URL using search query parameters. Any matching directories with your tenant will be returned as a paginated list.

Searchable Account Attributes

The following account attributes are searchable via filter and attribute searches:

  • givenName
  • middleName
  • surname
  • username
  • email

In addition to the search query parameters, you may also use pagination and sorting query parameters to customize the paginated response. For example:

curl -u $API_KEY_ID:$API_KEY_SECRET \
     -H "Accept: application/json" \
     "https://api.stormpath.com/v1/applications/$APPLICATION_ID/accounts?q=foo&orderBy=surname&offset=0&limit=50"

More Account Functionality

Account CRUD and other behavior that is not application-specific is covered in the main Accounts section.

Application Groups

As we’ve seen with application accounts, applications themselves also do not have direct groups of their own. Like accounts, groups are ‘owned’ by directories and instead made available to applications.

This means an application’s collection of groups is virtual. This virtual collection is an aggregate ‘view’ of all groups that are:

  1. directly assigned to the application as an account store
  2. in a directory that is assigned to the application as an account store

This is a powerful and convenient feature: as you add or remove account stores from an application to control its user population, you automatically ‘bring in’ any groups that may be assigned to your user accounts. You can interact with this collection, like search it or add groups to it, like you would a normal group collection.

You can then reference these groups in the application’s source code to check group membership and perform Role Based Access Control (RBAC). For example, you might have an “Admin” group and a “User” group which would enable very different functionality in your application when a user account is associated with one group or the other.

Most application developers do not need to be aware that an application’s groups collection is virtual. The most common case in Stormpath for simpler apps is to just create an application with its own directory for its own needs. Used this way, the application’s and the directory’s accounts and groups are the same.

But it is nice to know that you can customize the application’s account population with other directories or groups in the future if you need to do so.

Application Groups Collection Resource URI

/v1/applications/:applicationId/groups

Applications additionally support the following group-specific functionality:

Create a New Application Group

If your application wants to create a new group, POST the group resource attributes application’s groups endpoint.

Example Request

curl -X POST --user $YOUR_API_KEY_ID:$YOUR_API_KEY_SECRET \
     -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "Jedi High Council"
       "description": "Elected leaders of the Jedi Order."
       "status": "ENABLED"
     }' \
  "https://api.stormpath.com/v1/applications/bckhcGMXQDujIXpbCDRb2Q/groups"

Example Response

HTTP/1.1 201 Created
Location: https://api.stormpath.com/v1/groups/ZgoHUG0oSoVNeU0K4GZeVQ
Content-Type: application/json;charset=UTF-8;

{
  "href" : "https://api.stormpath.com/v1/groups/ZgoHUG0oSoVNeU0K4GZeVQ",
  "name" : "Jedi High Council",
  "description" : "Elected leaders of the Jedi Order.",
  "status" : "ENABLED",
  "directory" : {
    "href" : "https://api.stormpath.com/v1/directories/bckhcGMXQDujIXpbCDRb2Q"
  },
  "tenant" : {
    "href" : "https://api.stormpath.com/v1/tenants/Gh9238fksJlsieJkPkQuW"
  },
  "accounts" : {
    "href" : "https://api.stormpath.com/v1/groups/ZgoHUG0oSoVNeU0K4GZeVQ/accounts"
  }
}

How does this work?

As we mentioned above, an Application does not ‘own’ groups of its own – it has access to groups directly (or indirectly) assigned to it. So how are we able to create a new group based on only the application?

The v1/applications/:applicationId/groups URI is a convenience: when you POST a new group resource, Stormpath will automatically route that creation request to a designated directory assigned to the Application. The group is then persisted in that directory and then made immediately available to the application.

For most applications that have only a single assigned account store, the group is persisted in that account store immediately – the application developer does not even really need to know that Stormpath automates this.

However, applications that are assigned more than one account store have the option of specifying which of those mapped account stores should receive newly created groups. You can choose a default group store. If you do not choose one, the first one in the list of mapped account stores is the default location to store newly created groups. We’ll talk about setting the default group store and managing an application’s assigned account stores later in Application Account Store Mappings.

Create a New Application Group with your own Custom Data

When you create an application group, in addition to Stormpath’s group attributes, you may also specify your own custom data by including a customData JSON object:

curl -X POST --user $YOUR_API_KEY_ID:$YOUR_API_KEY_SECRET \
     -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -d '{
             "name" : "Jedi High Council",
             "description": "Elected leaders of the Jedi Order",
             "status": "ENABLED",
             "customData": {
                 "Headquarters": "High Council Chamber, High Council Tower, Jedi Temple, Coruscant",
                 "Affiliation": "Jedi Order",
             }
         }' \
     "https://api.stormpath.com/v1/applications/bckhcGMXQDujIXpbCDRb2Q/groups"

Once created, you can further modify the custom data – delete it, add and remove attributes, etc as necessary. See the custom data section for more information and customData requirements/restrictions.

List Application Groups

You can list your application’s groups by sending a GET request to your application’s groups Collection Resource href URL. The response is a paginated list of application groups.

You may also use collection pagination and sort ordering query parameters to customize the paginated response.

Example Request

curl -u $API_KEY_ID:$API_KEY_SECRET \
     -H "Accept: application/json" \
     "https://api.stormpath.com/v1/applications/$APPLICATION_ID/groups"

Example Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
  "href": "https://api.stormpath.com/v1/applications/cJoiwcorTTmkDDBsf02AbA/groups",
  "offset": 0,
  "limit": 25,
  "items" : [
    {
      "href" : "https://api.stormpath.com/v1/groups/WpM9nyZ2TbaEzfbRvLk9KA"
      ... remaining Group name/value pairs ...
    },
    {
      "href" : "https://api.stormpath.com/v1/groups/aLlyOUrBAse34js9hjiH9j"
      ... remaining Group name/value pairs ...
    },
    {
      "href" : "https://api.stormpath.com/v1/groups/Xhf0a9HLA02djsdP90dsQ2"
      ... remaining Group name/value pairs ...
    },
  ]
}

Search Application Groups

You may search for groups by sending a GET request to your application’s groups Collection Resource href URL using search query parameters. Any matching groups within your application will be returned as a paginated list.

Searchable Group Attributes

The following account attributes are searchable via filter and attribute searches:

  • name
  • description

In addition to the search query parameters, you may also use pagination and sorting query parameters to customize the paginated response. For example:

curl -u $API_KEY_ID:$API_KEY_SECRET \
     -H "Accept: application/json" \
     "https://api.stormpath.com/v1/applications/$APPLICATION_ID/groups?q=foo&orderBy=name&offset=0&limit=50"

More Group Functionality

Group CRUD and other behavior that is not application-specific is covered in the main Groups section.

Application Account Store Mappings

Stormpath uses the term Account Store to generically refer to either a group or a directory, since they both contain (store) accounts.

An application’s accountStoreMappings collection, then, reflects all groups and directories that are assigned to that application for the purpose of providing accounts that may login to the application. This is a powerful feature in Stormpath that allows you to control which account populations may login to an application.

However, many applications do not need this feature. The most common use case in Stormpath is to create an application and a single directory solely for the purpose of that application’s needs. This is a valid approach and a good idea when starting with Stormpath. However, rest assured that you have the flexibility to control your account populations in convenient ways as you expand to use Stormpath for any of your other applications.

You define and modify an application’s account store mappings by creating, modifying or deleting Account Store Mapping resources.

Application Account Store Mappings Collection Resource URI

/v1/applications/:applicationId/accountStoreMappings

List Application Account Store Mappings

You can list an application’s assigned account stores by sending a GET request to the application’s accountStoreMappings Collection Resource href URL. The response is a paginated list of application account store mappings.

You may also use collection pagination and sort ordering query parameters to customize the paginated response.

Example Request

curl -u $API_KEY_ID:$API_KEY_SECRET \
     -H "Accept: application/json" \
     "https://api.stormpath.com/v1/applications/$APPLICATION_ID/accountStoreMappings"

Example Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
  "href": "https://api.stormpath.com/v1/applications/5D26Bl8lHTct1FDCHrltc3/accountStoreMappings",
  "offset": 0,
  "limit": 25,
  "items" : [
    {
      "href" : "https://api.stormpath.com/v1/accountStoreMappings/XpM9nyZ2TbaEzfbRvLk9KA"
      ... remaining Account Store Mapping name/value pairs ...
    },
    {
      "href" : "https://api.stormpath.com/v1/accountStoreMappings/aLlyOUrBAse34js9hjiH9j"
      ... remaining Account Store Mapping name/value pairs ...
    },
    {
      "href" : "https://api.stormpath.com/v1/accountStoreMappings/Xhf0a9HLA02djsdP90dsQ2"
      ... remaining Account Store Mapping name/value pairs ...
    },
  ]
}

Account Store Mappings

Account Store is a generic term for either a Directory or a Group. Directories and Groups are both are considered “account stores” because they both contain, or ‘store’, Accounts. An Account Store Mapping, then, represents an Account Store mapped (assigned) to an Application.

In Stormpath, you control who may login to an application by associating (or ‘mapping’) one or more account stores to an application. All of the accounts across all of an application’s assigned account stores form the application’s effective user base; those accounts may login to the application. If no account stores are assigned to an application, no accounts will be able to login to the application.

You control which account stores are assigned (mapped) to an application, and the order in which they are consulted during a login attempt, by manipulating an application’s AccountStoreMapping resources.

How Login Attempts Work

When an account tries to login to your application, you submit a request to your application’s /loginAttempts endpoint. Stormpath then consults the application’s assigned account stores in the order that they are assigned to the application. When a matching account is discovered in a mapped account store, it is used to verify the authentication attempt and all subsequent account stores are ignored. In other words, accounts are matched for application login based on a ‘first match wins’ policy.

Let’s look at an example to illustrate this behavior. Assume that two account stores, a ‘Customers’ directory and an ‘Employees’ directory have been assigned (mapped) to a ‘Foo’ application, in that order.

The following flow chart shows what happens when an account attempts to login to the Foo application:

Account Stores Diagram

As you can see, Stormpath tries to find the account in the ‘Customers’ directory first because it has a higher priority than the ‘Employees’ directory. If not found, the ‘Employees’ directory is tried next as it has a lower priority.

You can assign multiple account stores to an application, but only one is required to enable login for an application. Assigning multiple account stores (directories or groups) to an application, as well as configuring their priority, allows you precise control over the account populations that may login to your various applications.

Account Store Mapping Resource

An individual accountStoreMapping resource may be accessed via its Resource URI:

Resource URI

/v1/accountStoreMappings/:accountStoreMappingId

Resource Attributes

Attribute Description Type Valid Value
href The account store mapping resource’s fully qualified location URI. String
application A link to the mapping’s Application. Required. link
accountStore A link to the mapping’s account store (either a Group or Directory) containing accounts that may login to the application. Required. link
listIndex The order (priority) when the associated accountStore will be consulted by the application during an authentication attempt. This is a zero-based index; an account store at listIndex of 0 will be consulted first (has the highest priority), followed the account store at listIndex 1 (next highest priority), etc. Setting a negative value will default the value to 0, placing it first in the list. A listIndex of larger than the current list size will place the mapping at the end of the list and then default the value to (list size - 1). Integer 0 <= N < list size
isDefaultAccountStore A true value indicates that new accounts created by the application will be automatically saved to the mapping’s accountStore. A false value indicates that new accounts created by the application will not be saved to the accountStore. boolean true,false
isDefaultGroupStore A true value indicates that new groups created by the application will be automatically saved to the mapping’s accountStore. A false value indicates that new groups created by the application will not be saved to the accountStore. This may only be set to true if the accountStore is a Directory. Stormpath does not currently support Groups storing other Groups. boolean true,false

For Account Store Mappings, you may:

Locate an Account Store Mapping’s REST URL

You locate an Account Store Mapping’s href by listing an Application’s associated Account Store Mappings. Within the list, find the AccountStoreMapping you need – it will have a unique href property.

Create an Account Store Mapping

In order for accounts in a Directory or Group to be able to login to an application, you must associate or ‘map’ the Directory or Group to the Application. You do this by creating a new AccountStoreMapping resource that references both the account store and application.

You do this by POSTing a new AccountStoreMapping resource to the /v1/accountStoreMappings URI. You must specify the application and the account store via their respective hrefs.

Required Attributes

Optional Attributes

Example Request

curl -X POST -u $API_KEY_ID:$API_KEY_SECRET \
     -H "Content-Type: application/json;charset=UTF-8" \
     -d '{
           "application": {
             "href": "https://api.stormpath.com/v1/applications/Uh8FzIouQ9C8EpcExAmPLe"
           }
           "accountStore": {
             "href": "https://api.stormpath.com/v1/directories/bckhcGMXQDujIXpExAmPLe"
           },
           "isDefaultAccountStore": true,
           "isDefaultGroupStore": true
         }' \
     'https://api.stormpath.com/v1/accountStoreMappings'

Example Response

{
    "href": "https://api.stormpath.com/v1/accountStoreMappings/7Ui2gpn9tV75y3TExAmPLe",
    "accountStore": {
        "href": "https://api.stormpath.com/v1/directories/bckhcGMXQDujIXpExAmPLe"
    },
    "application": {
        "href": "https://api.stormpath.com/v1/applications/Uh8FzIouQ9C8EpcExAmPLe"
    },
    "listIndex": 0,
    "isDefaultAccountStore": true,
    "isDefaultGroupStore": true
}

You may use the response’s Location header or the top-level href attribute to further interact with your new AccountStoreMapping resource.

Retrieve An Account Store Mapping

After you have created an account store mapping, you may retrieve its contents by sending a GET request to the account store mapping’s URL returned in the Location header or href attribute.

If you don’t have the account store mapping’s URL, you can find it in the application’s account store mappings list.

Example Request

GET https://api.stormpath.com/v1/accountStoreMappings/7Ui2gpn9tV75y3TExAmPLe

Example Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8;

{
    "href": "https://api.stormpath.com/v1/accountStoreMappings/7Ui2gpn9tV75y3TExAmPLe",
    "accountStore": {
        "href": "https://api.stormpath.com/v1/directories/bckhcGMXQDujIXpExAmPLe"
    },
    "application": {
        "href": "https://api.stormpath.com/v1/applications/Uh8FzIouQ9C8EpcExAmPLe"
    },
    "listIndex": 0,
    "isDefaultAccountStore": true,
    "isDefaultGroupStore": true
}

Expandable Resources

When retrieving an Account Store Mapping, you can also retrieve one or more of its linked resources by expanding them in-line using the expand query parameter.

The following AccountStoreMapping attributes are expandable:

  • accountStore
  • application

See the Link Expansion section for more information on expanding link attributes.

Update An Account Store Mapping

Submit an HTTP POST to an accountStoreMapping’s href when you want to change one or more of the account store mapping’s attributes. Unspecified attributes are not changed, but at least one attribute must be specified.

Updatable Application Attributes

Example Request

curl -X POST -u $API_KEY_ID:$API_KEY_SECRET \
     -H "Content-Type: application/json;charset=UTF-8" \
     -d '{
           "isDefaultAccountStore": true,
         }' \
     'https://api.stormpath.com/v1/accountStoreMappings/7Ui2gpn9tV75y3TExAmPLe'

Example Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8;

{
    "href": "https://api.stormpath.com/v1/accountStoreMappings/7Ui2gpn9tV75y3TExAmPLe",
    "accountStore": {
        "href": "https://api.stormpath.com/v1/directories/bckhcGMXQDujIXpExAmPLe"
    },
    "application": {
        "href": "https://api.stormpath.com/v1/applications/Uh8FzIouQ9C8EpcExAmPLe"
    },
    "listIndex": 0,
    "isDefaultAccountStore": true,
    "isDefaultGroupStore": true
}

Set the Login Priority of an Assigned Account Store

As we’ve shown previously, an account trying to login to an application will be matched to the application’s account stores based on the list order they are assigned to the application. The account store at list index 0 has the highest priority, the account store at list index 1 has the next highest priority, and so on. When an account is discovered in an account store, the login attempt occurs and returns immediately. All remaining account stores are not checked.

If you wish to change an account store’s login priority for an application, you simply:

  1. Find the accountStoreMapping resource in the application’s accountStoreMappings collection that reflects the accountStore that you wish to re-prioritize.
  2. Issue a POST update request to that AccountStoreMapping’s href with a new listIndex value.

Example Request

For example, assume that the account store represented by mapping https://api.stormpath.com/v1/accountStoreMappings/dRvH4y0nT6uNl6gExAmPLe has a list index of 0 (first in the list), and we wanted to lower its priority to 1 (second in the list):

curl -X POST -u $API_KEY_ID:$API_KEY_SECRET \
     -H "Content-Type: application/json;charset=UTF-8" \
     -d '{
           "listIndex": 1
         }' \
     'https://api.stormpath.com/v1/accountStoreMappings/dRvH4y0nT6uNl6gExAmPLe'

Example Response

{
    "href": "https://api.stormpath.com/v1/accountStoreMappings/dRvH4y0nT6uNl6gExAmPLe",
    "accountStore": {
        "href": "https://api.stormpath.com/v1/directories/bckhcGMXQDujIXpExAmPLe"
    },
    "application": {
        "href": "https://api.stormpath.com/v1/applications/Uh8FzIouQ9C8EpcExAmPLe"
    },
    "listIndex": 1,
    "isDefaultAccountStore": true,
    "isDefaultGroupStore": true
}

Set The Default Account Store for new Application Accounts

Applications cannot store Accounts directly – Accounts are always stored in an Account Store (a Directory or Group). Therefore, if you would like an application to be able to create new accounts, you must specify which of the application’s associated account stores should store the application’s newly created accounts. This designated account store is called the application’s default account store.

You specify an application’s default account store by setting the AccountStoreMapping’s isDefaultAccountStore attribute to equal true. You can do this when you create the accountStoreMapping resource. Or if the resource has already been created:

  1. Find the accountStoreMapping resource in the Application’s accountStoreMappings collection that reflects the accountStore you wish to be the application’s default account store.
  2. Issue a POST update request to that AccountStoreMapping’s href with isDefaultAccountStore set to true.

Example Request

curl -X POST -u $API_KEY_ID:$API_KEY_SECRET \
     -H "Content-Type: application/json;charset=UTF-8" \
     -d '{
           "isDefaultAccountStore": true
         }' \
     'https://api.stormpath.com/v1/accountStoreMappings/dRvH4y0nT6uNl6gExAmPLe'

Now, any time a new account is created by POSTing to the application’s https://api.stormpath.com/v1/applications/$APPLICATION_ID/accounts URI, the account will actually be created in the designated default account store.

Directory vs Group?

If the application’s default account store is a:

  • directory: the account will be created in the directory
  • group: the account will be created in the group’s directory first, then assigned to the group automatically.

Only one of an application’s mapped account stores may be the default account store.

In addition, setting an AccountStoreMapping’s isDefaultAccountStore value to true will automatically set the application’s other AccountStoreMappings’ isDefaultAccountStore values to false. However, note that setting an AccountStoreMapping’s isDefaultAccountStore value to false WILL NOT automatically set another AccountStoreMapping’s isDefaultAccountStore to true. You are responsible for explicitly setting isDefaultAccountStore to true if you want the application to be able to create new accounts.

If none of the application’s AccountStoreMappings are designated as the default account store, the application WILL NOT be able to create new accounts from the applications endpoint. It is still possible to create accounts from the accounts endpoint.

Also note that Mirrored directories or groups within Mirrored directories are read-only; they cannot be set as an application’s default account store. Attempting to set isDefaultAccountStore to true on an AccountStoreMapping that reflects a mirrored directory or group will result in an error response.

Set The Default Group Store for new Application Groups

Applications cannot store Groups directly – Groups are always stored in a Directory. Therefore, if you would like an application to be able to create new groups, you must specify which of the application’s associated account stores should store the application’s newly created groups. This designated store is called the application’s default group store.

You specify an application’s default group store by setting the AccountStoreMapping’s isDefaultGroupStore attribute to equal true. You can do this when you create the accountStoreMapping resource, or if the resource has already been created:

  1. Find the accountStoreMapping resource in the Application’s accountStoreMappings collection that reflects the accountStore you wish to be the application’s default group store.
  2. Issue a POST update request to that AccountStoreMapping’s href with isDefaultGroupStore set to true.

Example Request

curl -X POST -u $API_KEY_ID:$API_KEY_SECRET \
     -H "Content-Type: application/json;charset=UTF-8" \
     -d '{
           "isDefaultGroupStore": true
         }' \
     'https://api.stormpath.com/v1/accountStoreMappings/dRvH4y0nT6uNl6gExAmPLe'

Now, any time a new group is created by POSTing to the application’s https://api.stormpath.com/v1/applications/$APPLICATION_ID/groups URI, the group will actually be created in the designated default group store.

Only one of an application’s mapped account stores may be the default group store.

Also, note that setting an AccountStoreMapping’s isDefaultGroupStore value to true will automatically set the application’s other AccountStoreMappings’ isDefaultGroupStore values to false. HOWEVER:

Lastly, setting an AccountStoreMapping’s isDefaultGroupStore value to false WILL NOT automatically set another AccountStoreMapping’s isDefaultGroupStore to true. You are responsible for explicitly setting isDefaultGroupStore to true if you want the application to be able to create new groups.

If no AccountStoreMapping is designated as the default group store, the application WILL NOT be able to create new groups.

Also, note that Stormpath does not currently support storing groups within groups. Therefore isDefaultGroupStore can only be set to true when the AccountStoreMapping’s accountStore is a Directory. Attempting to set isDefaultGroupStore to true on an AccountStoreMapping that reflects a group will result in an error response.

Lastly, note that mirrored directories are read-only; they cannot be set as an application’s default group store. Attempting to set isDefaultGroupStore to true on an AccountStoreMapping that reflects a mirrored directory will result in an error response.

Delete an Account Store Mapping

You remove an assigned account store from an application by DELETEing the accountStoreMapping resource that links the accountStore and the application together. This removes the possibility of the accounts in the associated account store from being able to login to the application.

Deleting an accountStoreMapping resource does not delete either the account store or the application resources themselves - only the association between the two.

Deleting an account store mapping will remove the ability for accounts in the account store from authenticating with the application unless they are associated with an account store that is still mapped to the application. Be careful when removing mappings.

Also, note that if no AccountStoreMapping is designated as the default account store, the application WILL NOT be able to create new accounts. Similarly, if there is no designated default group store, the application will not be able to create new groups.

Example Request

For example, to delete the application-accountStore association we created in the above previous example:

curl -X DELETE -u $API_KEY_ID:$API_KEY_SECRET \
     'https://api.stormpath.com/v1/accountStoreMappings/7Ui2gpn9tV75y3TExAmPLe'

Example Response

HTTP/1.1 204 No Content

List Account Store Mappings

You can list an applications’s mapped account stores by issuing a GET request to the application’s accountStoreMappings href URI.

The response is a paginated list of accountStoreMapping resources. You may use collection pagination query parameters to customize the paginated response.

Example Request

curl -u $API_KEY_ID:$API_KEY_SECRET \
     -H "Accept: application/json" \
     "https://api.stormpath.com/v1/applications/3hFENJHLaH1Vy4GSbscrtv/accountStoreMappings"

Example Response

{
   "href":"https://api.stormpath.com/v1/applications/3hFENJHLaH1Vy4GSbscrtv/accountStoreMappings",
   "offset":0,
   "limit":25,
   "items":[
      {
         "href":"https://api.stormpath.com/v1/accountStoreMappings/3hGLY9yHEqYraR0cXJUDPD",
         "listIndex":0,
         "isDefaultAccountStore":true,
         "isDefaultGroupStore":true,
         "application":{
            "href":"https://api.stormpath.com/v1/applications/3hFENJHLaH1Vy4GSbscrtv"
         },
         "accountStore":{
            "href":"https://api.stormpath.com/v1/directories/3hFN1PriI5xvv76jLoEXL5"
         }
      },
      ... remaining AccountStoreMappings ...
   ]
}

Directories

A Directory is a top-level storage containers of Accounts and Groups. A Directory also manages security policies (like password strength) for the Accounts it contains.

Additionally:

  • All Accounts within a directory have a unique email address and/or username.
  • All Groups within a directory have a unique name.

Stormpath supports two types of Directories:

  1. Natively hosted ‘Cloud’ directories that originate in Stormpath and
  2. ‘Mirror’ directories that act as secure mirrors or replicas of existing directories outside of Stormpath, for example LDAP or Active Directory servers.

Directories are a more advanced feature of Stormpath. If you have a single application or multiple applications that access the same accounts, you usually only need a single directory, and you do not need to be concerned with creating or managing multiple directories.

If however, your application(s) needs to support login for external 3rd party accounts like those in LDAP or Active Directory, or you have more complex account segmentation needs, directories will be a powerful tool to manage your application(s) user base.

Directories can be used to cleanly manage segmented account populations. For example, you might use one Directory for company employees and another Directory for customers, each with its own security policies. You can associate directories to applications (or groups within a directory) to allow the directory’s accounts to login to applications.

You can add as many directories of each type as you require. Adding or deleting accounts, groups and group memberships in directories affects ALL applications to which the directories are mapped as account stores.

Mirror Directories

Mirror directories are a big benefit to Stormpath customers who need LDAP or Active Directory accounts to be able to securely login to public web applications without breaking corporate firewall policies. Here is how they work:

  • After creating an LDAP or AD Directory in Stormpath, you download a Stormpath Agent. This is a simple standalone software application that you install behind the corporate firewall so it can communicate directly with the LDAP or AD server.
  • You configure the agent via LDAP filters to view only the accounts that you want to expose to your Stormpath-enabled applications.
  • The Agent will start synchronizing immediately, pushing this select data outbound to Stormpath over a TLS (HTTPS) connection.
  • The synchronized accounts and groups appear in the Stormpath Directory. The accounts will be able to login to any Stormpath-enabled application that you assign.
  • When the Agent detects local LDAP or AD changes, additions or deletions to these specific accounts or groups, it will automatically propagate those changes to Stormpath to be reflected by your Stormpath-enabled applications.

LDAP or Active Directory are still the ‘system of record’ or source of identity ‘truth’ for these accounts and groups. The big benefit is that your Stormpath-enabled applications still use the same convenient REST+JSON API – they do not need to know anything about LDAP, Active Directory or legacy connection protocols!

The Stormpath Agent is firewall friendly: you do not need to open any inbound holes in your company firewall. The only requirement is that the Agent be able to make an outbound HTTPS connection to https://api.stormpath.com

Finally, note that accounts and groups in mirrored directories are automatically deleted when:

  • The original object is deleted from the LDAP or AD directory service.
  • The original LDAP/AD object information no longer matches the account filter criteria configured for the agent.
  • The LDAP/AD directory is deleted.

Directory Resource

An individual directory resource may be accessed via its Resource URI:

Resource URI

/v1/directories/:directoryId

Resource Attributes

Attribute Description Type Valid Value
href The resource fully qualified location URI String
name Name of the directory. Must be unique within a tenant. String 1 < N <= 255 characters
description The description of the directory. String 0 < N <= 1000 characters
status Enabled directories can be used as account stores for applications. Disabled directories cannot be used for login. Enum enabled,disabled
accounts A link to the accounts owned by the directory. Link
groups A link to the groups owned by the directory. Link
tenant A link to the owning tenant. Link

For directories, you can:

Locate a Directory’s REST URL

When communicating with the Stormpath REST API, you might need to reference a directory using its REST URL or href.

There are multiple ways to find a directory href depending on what information you have available:

For example, if you need the href for a directory named “My Directory”, you can search your tenant’s directories collection:

Example Request

curl -u $API_KEY_ID:$API_KEY_SECRET \
     -H "Accept: application/json" \
     "https://api.stormpath.com/v1/tenants/23mq7BPIxNgPUPZDwj04SZ/directories?name=My%20Directory"

Example Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
    "href": "https://api.stormpath.com/v1/tenants/23mq7BPIxNgPUPZDwj04SZ/directories",
    "offset": 0,
    "limit": 25,
    "items": [
      {
        "href": "https://api.stormpath.com/v1/directories/3hFENJHLaH1Vy4GSbscrtv"
        "name": "My Directory"
        ... remaining Directory name/value pairs ...
      }
    ]
}

If you know the name exactly, you can use an attribute search (e.g., name=) or, if you only know a small part, you can use a filter search (e.g., q=My) to narrow the results.

Create a Directory

It is currently only possible to create a standard (non-mirrored) Directory via the REST API. If you need to create a mirror directory for LDAP or Active Directory, you must use the Stormpath Admin Console.

Create a Cloud Directory

You create a new directory by submitting an HTTP POST request to the /v1/directories endpoint. This will create a new Directory instance within the caller’s tenant.

When you submit the POST, at least the name attribute must be specified, and it must be unique compared to all other directories in your tenant. The description and status attribute are optional.

Required Attribute

Optional Attributes

Example Request

POST https://api.stormpath.com/v1/directories
Content-Type: application/json;charset=UTF-8

{
  "name" : "Captains",
  "description" : "Captains from a variety of stories"
}

Example Response

HTTP/1.1 201 Created
Location: https://api.stormpath.com/v1/directories/bckhcGMXQDujIXpbCDRb2Q
Content-Type: application/json;charset=UTF-8;

{
  "href" : "https://api.stormpath.com/v1/directories/bckhcGMXQDujIXpbCDRb2Q",
  "name" : "Captains",
  "description" : "Captains from a variety of stories",
  "status" : "ENABLED",
  "tenant" : {
    "href" : "https://api.stormpath.com/v1/tenants/Gh9238fksJlsieJkPkQuW"
  },
  "accounts" : {
    "href" : "https://api.stormpath.com/v1/directories/bckhcGMXQDujIXpbCDRb2Q/accounts"
  },
  "groups" : {
    "href" : "https://api.stormpath.com/v1/directories/bckhcGMXQDujIXpbCDRb2Q/groups"
  }
}

Create a Mirrored (LDAP/AD) Directory

It is currently only possible to create a standard (non-mirrored) Directory via the REST API. If you need to create a mirror directory for LDAP or Active Directory, you must use the Stormpath Admin Console.

Associate Directories with Applications

If you want to assign a directory to an application so the directory’s accounts may login to the application, you will need to create an AccountStoreMapping.

Retrieve a Directory

To retrieve a Directory, execute a GET request to a directory’s href:

Example Request

GET https://api.stormpath.com/v1/directories/bckhcGMXQDujIXpbCDRb2Q

Example Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8;

{
  "href" : "https://api.stormpath.com/v1/directories/bckhcGMXQDujIXpbCDRb2Q",
  "name" : "Captains",
  "description" : "Captains from a variety of stories",
  "status" : "enabled",
  "accounts" : {
    "href" : "https://api.stormpath.com/v1/directories/bckhcGMXQDujIXpbCDRb2Q/accounts"
  },
  "groups" : {
    "href" : "https://api.stormpath.com/v1/directories/bckhcGMXQDujIXpbCDRb2Q/groups"
  },
  "tenant" : {
    "href" : "https://api.stormpath.com/v1/tenants/Gh9238fksJlsieJkPkQuW"
  }
}

Expandable Resources

When retrieving a directory, you can also retrieve one or more of its linked resources by expanding them in-line using the expand query parameter.

The following Directory attributes are expandable:

  • accounts
  • groups
  • tenant

Also, because accounts, groups, and the tenant are Collection Resources themselves, you can additionally control pagination for either expanded collection. For example:

GET https://api.stormpath.com/v1/directories/bckhcGMXQDujIXpbCDRb2Q?expand=tenant,groups(offset:0,limit:50),accounts(offset:0,limit:50)

See the Link Expansion section for more information on expanding link attributes.

Update a Directory

Use HTTP POST when you want to change one or more specific attributes of a directory resource. Unspecified attributes will not be changed, but at least one attribute must be specified.

Optional Attributes

Example Request

POST https://api.stormpath.com/v1/directories/bckhcGMXQDujIXpbCDRb2Q
Content-Type: application/json;charset=UTF-8

{
  "name" : "Captains Directory",
}

Example Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8;

{
  "href" : "https://api.stormpath.com/v1/directories/bckhcGMXQDujIXpbCDRb2Q",
  "name" : "Captains Directory",
  "description" : "Captains from a variety of stories",
  "status" : "enabled",
  "tenant" : {
    "href" : "https://api.stormpath.com/v1/tenants/Gh9238fksJlsieJkPkQuW"
  },
  "accounts" : {
    "href" : "https://api.stormpath.com/v1/directories/bckhcGMXQDujIXpbCDRb2Q/accounts"
  },
  "groups" : {
    "href" : "https://api.stormpath.com/v1/directories/bckhcGMXQDujIXpbCDRb2Q/groups"
  }
}

Enable Or Disable a Directory

A directory’s status can be either enabled or disabled. An enabled directory allows its accounts and groups to login to any assigned application. A disabled directory does not allow its accounts and groups to login to applications.

To enable or disable a directory, use HTTP POST to set the status to either ENABLED or DISABLED.

Example Request

POST https://api.stormpath.com/v1/directories/bckhcGMXQDujIXpbCDRb2Q
 Content-Type: application/json;charset=UTF-8

 {
   "status" : "ENABLED",
 }

Update Agent Configuration

A Directory Agent is a Stormpath software application installed on your corporate network to securely synchronize an on-premise directory, such as LDAP or Active Directory, into a Stormpath mirror directory.

You can modify an agent configuration going through the “Directories” or “Agent” tabs on the Stormpath Admin Console. For more information on administering Mirrored Directory agents, refer to the Stormpath Admin Console product guide.

Delete a Directory

Deleting a directory completely erases the directory and all of its accounts and groups from Stormpath.

We recommend that you disable a directory instead of deleting it if you anticipate that you might use the directory again or if you want to retain its data for historical reference.

To delete a directory:

Example Request

DELETE https://api.stormpath.com/v1/directories/bckhcGMXQDujIXpbCDRb2Q

Example Response

HTTP/1.1 204 No Content

The Stormpath Administrators directory cannot be deleted.

List Directories

You may list your tenant’s directories as described in List Tenant Directories.

Search Directories

You may search for directories as described in Search Tenant directories.

Account Password Policy

Directories can be configured to enforce specific restrictions on passwords for accounts associated with, such as requiring at least one or more non-alphanumeric characters.

With Stormpath’s Cloud directories, you can configure custom restrictions for the passwords on accounts associated with that directory. You can specify the following elements in your directory’s password requirements:

  • Min characters
  • Max characters
  • Mandatry characters
    • Lower case alphabetical
    • Uppercase case alphabetical
    • Numeric
    • Punctuation
    • Special characters (e.g., é)

By default, passwords must be of mixed case, include at least one number, and be between 8 and 100 characters in length.

It is not currently possible to configure a Directory’s account password policy via the REST API. You must use the Stormpath Admin Console (Directories –> <choose your directory> –> Details tab).

Workflows are only available on cloud directories and only configurable using the Stormpath Admin Console. They are not currently configurable via the REST API.

Additionally, the Stormpath Administrator directory’s automated workflows cannot be altered.

Register A New Account

This workflow allows you to create an account at an application level rather than at a directory level. The application will populate the directory set as the default account store.

This workflow relies on the account resource as a starting point. For more information on working with these workflows via REST after they have already been configured, refer to the Working With Applications section of this guide. This workflow is disabled by default for accounts, but you can enable it easily in the Stormpath Admin Console UI. Refer to the Stormpath Admin Console product guide for complete instructions.

Workflows are only available on cloud directories and only configurable using the Stormpath Admin Console. They are not currently configurable via the REST API. Also, the Stormpath Administrator directory’s automated workflows cannot be altered.

Work With Accounts

If you want to learn about other account functionalities, such as verify an email address, log in (authenticate) an account and reset an account password, read the instructions below.

Verify An Account’s Email Address

This workflow allows you to send a welcome email to a newly registered account and optionally verify that they own the email addressed used during registration.

The email verification workflow involves changes to an account at an application level, and as such, this workflow relies on the account resource as a starting point. For more information on working with these workflows via REST after they have already been configured, refer to the Working With Accounts section of this guide. This workflow is disabled by default for accounts, but you can enable it easily in the Stormpath Admin Console UI. Refer to the Stormpath Admin Console product guide for complete instructions.

Workflows are only available on cloud directories and only configurable using the Stormpath Admin Console. They are not currently configurable via the REST API. Also, the Stormpath Administrator directory’s automated workflows cannot be altered.

This is a self-service password reset workflow. The account is sent an email with a secure link. The person owning the account can click on the link and be shown a password reset form to reset their password. This is strongly recommended to reduce support requests to your application team as well as to reduce your exposure to account passwords for added security.

The password reset workflow involves changes to an account at an application level, and as such, this workflow relies on the application resource as a starting point. For more information on working with this workflow via REST after they have already been configured, refer to the Working With Applications section of this guide.

This workflow is disabled by default for accounts, but you can enable it easily in the Stormpath Admin Console UI. Refer to the Stormpath Admin Console product guide for complete instructions.

Workflows are only available on cloud directories and only configurable using the Stormpath Admin Console. They are not currently configurable via the REST API. Also, the Stormpath Administrator directory’s automated workflows cannot be altered.

Directory Groups

The Groups Collections for a Directory Resource Collection Resource represents all groups owned by a specific directory.

Directory Groups Collection Resource URI

/v1/directories/:directoryId/groups

List Directory Groups

You can list your directory’s groups by sending a GET request to your directory’s groups Collection Resource href URL. The response is a paginated list of directory groups.

You may also use collection pagination and sort ordering query parameters to customize the paginated response.

Example Request

curl -u $API_KEY_ID:$API_KEY_SECRET \
     -H "Accept: application/json" \
     "https://api.stormpath.com/v1/directories/$DIRECTORY_ID/groups"

Example Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
  "href": "https://api.stormpath.com/v1/directories/5D1bvO5To6KQBaGFh793Zz/groups",
  "offset": 0,
  "limit": 25,
  "items" : [
    {
      "href" : "https://api.stormpath.com/v1/groups/WpM9nyZ2TbaEzfbRvLk9KA"
      ... remaining Group name/value pairs ...
    },
    {
      "href" : "https://api.stormpath.com/v1/groups/aLlyOUrBAse34js9hjiH9j"
      ... remaining Group name/value pairs ...
    },
    {
      "href" : "https://api.stormpath.com/v1/groups/Xhf0a9HLA02djsdP90dsQ2"
      ... remaining Group name/value pairs ...
    },
  ]
}

Search Directory Groups

You may search for groups by sending a GET request to your directory’s groups Collection Resource href URL using search query parameters. Any matching groups within your directory will be returned as a paginated list.

Searchable Group Attributes

The following account attributes are searchable via filter and attribute searches:

  • name
  • description

In addition to the search query parameters, you may also use pagination and sorting query parameters to customize the paginated response. For example:

curl -u $API_KEY_ID:$API_KEY_SECRET \
     -H "Accept: application/json" \
     "https://api.stormpath.com/v1/directories/$DIRECTORY_ID/groups?q=foo&orderBy=name&offset=0&limit=50"

Working With Directory Groups

Group resources support the full suite of CRUD commands and other interactions. Please see the Groups section for more information.

Directory Accounts

The Accounts Collection for a Directory Resource Collection Resource represents all accounts owned by a specific directory.

Directory Accounts Collection Resource URI

/v1/directories/:directoryId/accounts

List Directory Accounts

You can list your directory’s accounts by sending a GET request to your directory’s groups Collection Resource href URL. The response is a paginated list of directory groups.

You may also use collection pagination and sort ordering query parameters to customize the paginated response.

Example Request

curl -u $API_KEY_ID:$API_KEY_SECRET \
     -H "Accept: application/json" \
     "https://api.stormpath.com/v1/directories/$DIRECTORY_ID/groups"

Example Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
  "href": "https://api.stormpath.com/v1/directories/5D1bvO5To6KQBaGFh793Zz/groups",
  "offset": 0,
  "limit": 25,
  "items" : [
    {
      "href" : "https://api.stormpath.com/v1/groups/WpM9nyZ2TbaEzfbRvLk9KA"
      ... remaining Group name/value pairs ...
    },
    {
      "href" : "https://api.stormpath.com/v1/groups/aLlyOUrBAse34js9hjiH9j"
      ... remaining Group name/value pairs ...
    },
    {
      "href" : "https://api.stormpath.com/v1/groups/Xhf0a9HLA02djsdP90dsQ2"
      ... remaining Group name/value pairs ...
    },
  ]
}

Search Directory Accounts

You may search for accounts by sending a GET request to your directory’s account Collection Resource href URL using search query parameters. Any matching groups within your directory will be returned as a paginated list.

Searchable Account Attributes

The following account attributes are searchable via filter and attribute searches:

  • username
  • email
  • givenName
  • middleName
  • surname

In addition to the search query parameters, you may also use pagination and sorting query parameters to customize the paginated response. For example:

curl -u $API_KEY_ID:$API_KEY_SECRET \
     -H "Accept: application/json" \
     "https://api.stormpath.com/v1/directories/$DIRECTORY_ID/accounts?q=foo&orderBy=surname&offset=0&limit=50"

Working With Directory Accounts

Account resources support the full suite of CRUD commands and other interactions. Please see the Accounts section for more information.


Groups

A Group is a collection of Accounts within a Directory that are often used for authorization and access control to the Application. In Stormpath, the term Group is synonymous with role.

You manage LDAP/AD groups on your primary LDAP/AD installation. LDAP/AD accounts and groups are automatically deleted when:

  • The backing object is deleted from the LDAP/AD directory service.
  • The backing LDAP/AD object information no longer matches the account filter criteria configured for the agent.
  • The LDAP/AD directory is deleted.

Group Resource

Resource URI

/v1/groups/:groupId

Resource Attributes

Attribute Description Type Valid Value
href The resource fully qualified location URI String
name The name of the group. Must be unique within a directory. String 1 < N <= 255 characters
description The description of the group. String 1 < N <= 1000 characters
status Enabled groups are able to authenticate against an application. Disabled groups cannot authenticate against an application. Enum enabled,disabled
customData A link to the group’s customData resource that you can use to store your own group-specific custom fields. Link
tenant The tenant that owns the directory containing this group. Link
directory A link to the directory resource that the group belongs to. Link
accounts A link to the accounts that are contained within this group. Link

With groups, you can:

Locate a Group’s REST URL

When communicating with the Stormpath REST API, you might need to reference a group directly using its REST URL or href.

There are multiple ways to find a group href depending on what information you have available:

  • Retrieve a group from a specific directory
  • Retrieve a group from a specific account’s groupMemberships.
  • Retrieve a group from the application’s full list of groups

In all cases, the process is fundamentally the same. Consider the first case as example.

In order to locate a group’s href, you’ll need to first search the tenant for the specific group using some information that you have available.

For example, if you want to find the href for a group with the name “My Group”, you’ll need to search the directory for the “My Group” group resource:

Example Request

curl -u $API_KEY_ID:$API_KEY_SECRET \
     -H "Accept: application/json" \
     "https://api.stormpath.com/v1/directories/5D1bvO5To6KQBaGFh793Zz/groups?name=My%20GROUP"

Example Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
    href: "https://api.stormpath.com/v1/directories/5D1bvO5To6KQBaGFh793Zz/groups"
    offset: 0
    limit: 25
    items: [1]
      0:  {
        href: "https://api.stormpath.com/v1/groups/cquoM06qa6pTkk1h2xOeJ"
        name: "My Group"
        ... remaining Account name/value pairs ...
}

If you know the name exactly, you can use an attribute search (e.g., “name=”) or, if you only know a small part, you can use a filter search (e.g., “q=My”) to narrow down the selection.

Create a Group

To create a new group resource instance in a specified directory which is accessible to the application:

Resource URI

/v1/directories/:directoryId/groups

Required Attributes

Optional Attributes

Example Request

POST https://api.stormpath.com/v1/directories/bckhcGMXQDujIXpbCDRb2Q/groups
Content-Type: application/json;charset=UTF-8

{
  "name" : "Aquanauts",
  "description" : "Sea Voyagers",
  "status" : "enabled"
}

Example Response

HTTP/1.1 201 Created
Location: https://api.stormpath.com/v1/groups/ZgoHUG0oSoVNeU0K4GZeVQ
Content-Type: application/json;charset=UTF-8;

{
  "href" : "https://api.stormpath.com/v1/groups/ZgoHUG0oSoVNeU0K4GZeVQ",
  "name" : "Aquanauts",
  "description" : "Sea Voyagers",
  "status" : "enabled",
  "directory" : {
    "href" : "https://api.stormpath.com/v1/directories/bckhcGMXQDujIXpbCDRb2Q"
  },
  "tenant" : {
    "href" : "https://api.stormpath.com/v1/tenants/Gh9238fksJlsieJkPkQuW"
  },
  "accounts" : {
    "href" : "https://api.stormpath.com/v1/groups/ZgoHUG0oSoVNeU0K4GZeVQ/accounts"
  }
}

This creates a new group in the application group creation acceptable designated directory. The group data POSTed is the same required for the existing directory-specific group creation endpoint.

If there is no acceptable designated directory account store, the REST API error code 5102 is returned:

{
  "status": 409,
  "code": 5102,
  "message": "Oops! We encountered an unexpected error.  Please contact support and explain what you were doing at the time this error occurred.",
  "developerMessage": "No account store assigned to this application has been configured as the default storage location for newly created groups.  To fix this problem: in the application's 'account stores' configuration, specify the account store that will be used to store newly created groups."
  "moreInfo": "http://docs.stormpath.com/errors/5102"
}

Retrieve a Group

HTTP GET returns a representation of a group resource that includes the resource attributes.

Example Request

GET https://api.stormpath.com/v1/groups/ZgoHUG0oSoVNeU0K4GZeVQ

Example Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8;

{
  "href" : "https://api.stormpath.com/v1/groups/ZgoHUG0oSoVNeU0K4GZeVQ",
  "name" : "Aquanauts",
  "description" : "Sea Voyagers",
  "status" : "enabled",
  "directory" : {
    "href" : "https://api.stormpath.com/v1/directories/bckhcGMXQDujIXpbCDRb2Q"
  },
  "tenant" : {
    "href" : "https://api.stormpath.com/v1/tenants/Gh9238fksJlsieJkPkQuW"
  },
  "accounts" : {
    "href" : "https://api.stormpath.com/v1/groups/ZgoHUG0oSoVNeU0K4GZeVQ/accounts"
  }
}

Expandable Resources

When retrieving an application, you can also retrieve one or more of its linked resources by expanding them in-line using the expand query parameter.

The following Groups attributes are expandable:

  • tenant
  • directory
  • accounts

Also, because accounts is a Collection Resources itself, you can additionally control pagination for either expanded collection. For example:

GET https://api.stormpath.com/v1/groups/WpM9nyZ2TbaEzfbRvLk9KA?expand=tenant,directory,accounts(offset:0,limit:50)

See the Link Expansion section for more information on expanding link attributes.

Update a Group

Use HTTP POST when you want to change one or more specific attributes of a group resource. Unspecified attributes are not changed, but at least one attribute must be specified.

Optional Attributes

Here are some account update examples:

Example Request

POST https://api.stormpath.com/v1/groups/ZgoHUG0oSoVNeU0K4GZeVQ
Content-Type: application/json;charset=UTF-8

{
  "description" : "Sea Voyagers"
}

Example Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8;

{
  "href" : "https://api.stormpath.com/v1/groups/ZgoHUG0oSoVNeU0K4GZeVQ",
  "name" : "Aquanauts",
  "description" : "Sea Voyagers",
  "status" : "enabled",
  "directory" : {
    "href" : "https://api.stormpath.com/v1/directories/bckhcGMXQDujIXpbCDRb2Q"
  },
  "tenant" : {
    "href" : "https://api.stormpath.com/v1/tenants/Gh9238fksJlsieJkPkQuW"
  },
  "accounts" : {
    "href" : "https://api.stormpath.com/v1/groups/ZgoHUG0oSoVNeU0K4GZeVQ/accounts"
  }
}

Enable a Group

If the group is contained within an enabled directory where the directory is defined as an account store, then enabling the group allows all accounts contained within the group (membership list) to log in to any applications for which the directory is defined as an account store.

If the group is contained within an disabled directory where the directory is defined as an account store, the group members are not be able to log in to any applications for which the directory is defined as an account store.

If the group is defined as an account store, then enabling the group allows accounts contained within the group (membership list) to log in to any applications for which the group is defined as an account store.

To enable a group:

Example Request

POST https://api.stormpath.com/v1/groups/ZgoHUG0oSoVNeU0K4GZeVQ
 Content-Type: application/json;charset=UTF-8

 {
   "status" : "ENABLED"
 }

Example Response

HTTP/1.1 200 OK
 Content-Type: application/json;charset=UTF-8;

 {
   "href" : "https://api.stormpath.com/v1/groups/ZgoHUG0oSoVNeU0K4GZeVQ",
   "name" : "Aquanauts",
   "description" : "Sea Voyagers",
   "status" : "enabled",
   "directory" : {
 "href" : "https://api.stormpath.com/v1/directories/bckhcGMXQDujIXpbCDRb2Q"
   },
   "tenant" : {
 "href" : "https://api.stormpath.com/v1/tenants/Gh9238fksJlsieJkPkQuW"
   },
   "accounts" : {
 "href" : "https://api.stormpath.com/v1/groups/ZgoHUG0oSoVNeU0K4GZeVQ/accounts"
   }
 }

Disable a Group

If a group is explicitly set as an application account store, then disabling that group prevents any of its user accounts from logging into that application but retains the group data and memberships. You would typically disable a group if you must shut off a group of user accounts quickly and easily.

If the group is contained within a directory defined as an account store, disabling the group prevents group members from logging in to any applications for which the directory is defined as an account store.

To disable a group:

Example Request

POST https://api.stormpath.com/v1/groups/ZgoHUG0oSoVNeU0K4GZeVQ
 Content-Type: application/json;charset=UTF-8

 {
   "status" : "DISABLED"
 }

Example Response

HTTP/1.1 200 OK
 Content-Type: application/json;charset=UTF-8;

 {
   "href" : "https://api.stormpath.com/v1/groups/ZgoHUG0oSoVNeU0K4GZeVQ",
   "name" : "Aquanauts",
   "description" : "Sea Voyagers",
   "status" : "disabled",
   "directory" : {
     "href" : "https://api.stormpath.com/v1/directories/bckhcGMXQDujIXpbCDRb2Q"
   },
   "tenant" : {
     "href" : "https://api.stormpath.com/v1/tenants/Gh9238fksJlsieJkPkQuW"
   },
   "accounts" : {
     "href" : "https://api.stormpath.com/v1/groups/ZgoHUG0oSoVNeU0K4GZeVQ/accounts"
   }
 }

Delete a Group

Deleting a cloud directory group erases the group and all its membership relationships. User accounts that are members of the group will not be deleted.

We recommend that you disable an group rather than delete it, if you believe you might need to retain the user data or application connection.

To delete a cloud directory group:

Example Request

DELETE https://api.stormpath.com/v1/groups/ZgoHUG0oSoVNeU0K4GZeVQ

Example Response

HTTP/1.1 204 No Content

Group Custom Data

While Stormpath’s default Group attributes are useful to many applications, you might want to add your own custom data to a Stormpath group. If you want, you can store all of your custom group information in Stormpath so you don’t have to maintain another separate database to store your specific group data.

Please see the custom data section for more information and requirements/restrictions for creating, retrieving, updating and deleting group custom data.

List Groups

Application Groups

The application groups endpoint is a Collection Resource representing all application-accessible groups. A group is accessible to an application if it, or its directory, is assigned to the application as an account store.

/v1/applications/:applicationUid/groups

HTTP GET returns a paginated list of links for groups accessible to an application.

Example request:

GET https://api.stormpath.com/v1/applications/WpM9nyZ2TbaEzfbRvLk9KA/groups

Example response:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8;

{
  "href": "https://api.stormpath.com/v1/applications/WpM9nyZ2TbaEzfbRvLk9KA/groups"
  "offset": 0,
  "limit": 25,
  "items" : [
    {
      "href" : "https://api.stormpath.com/v1/groups/ZgoHUG0oSoVNeU0K4GZeVQ"
      "name": "Red Shirts",
      ... remaining Group key/value pairs ...
    },
    {
      "href" : "https://api.stormpath.com/v1/groups/sUcKIttrebEcKhgU86Kl0u"
      "name": "Science Officers",
      ... remaining Group key/value pairs ...
    },
    {
      "href" : "https://api.stormpath.com/v1/groups/Yu8ihas7HOpjHs3uhd7jGd"
      "name": "Security Team",
      ... remaining Group key/value pairs ...
    }
  ]
}
Account Groups

The account groups resource is a Collection Resource representing all account-associated groups. A group is associated with an account when an account has been assigned to that group as a member.

/v1/accounts/:accountUid/groups

HTTP GET returns a paginated list of links for groups for which an account is a member.

Example Request

GET https://api.stormpath.com/v1/accounts/cJoiwcorTTmkDDBsf02AbA/groups

Example Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8;

{
  "href": "https://api.stormpath.com/v1/accounts/cJoiwcorTTmkDDBsf02AbA/groups"
  "offset": 0,
  "limit": 25,
  "items" : [
    {
      "href" : "https://api.stormpath.com/v1/groups/ZgoHUG0oSoVNeU0K4GZeVQ"
      "name": "Red Shirts",
      ... remaining Group key/value pairs ...
    },
    {
      "href" : "https://api.stormpath.com/v1/groups/sUcKIttrebEcKhgU86Kl0u"
      "name": "Science Officers",
      ... remaining Group key/value pairs ...
    },
    {
      "href" : "https://api.stormpath.com/v1/groups/Yu8ihas7HOpjHs3uhd7jGd"
      "name": "Security Team",
      ... remaining Group key/value pairs ...
    }
  ]
}
Directory Groups

The directory groups resource is a Collection Resource representing all directory-associated groups. Groups are defined as a subset of members in a directory.

/v1/directories/:directoryUid/groups

HTTP GET returns a paginated list of links for groups for which an account is a member.

Example Request

GET https://api.stormpath.com/v1/directories/bckhcGMXQDujIXpbCDRb2Q/groups

Example Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8;

{
  "href": "https://api.stormpath.com/v1/directories/bckhcGMXQDujIXpbCDRb2Q/groups"
  "offset": 0,
  "limit": 25,
  "items" : [
    {
      "href" : "https://api.stormpath.com/v1/groups/ZgoHUG0oSoVNeU0K4GZeVQ"
      "name": "Red Shirts",
      ... remaining Group key/value pairs ...
    },
    {
      "href" : "https://api.stormpath.com/v1/groups/sUcKIttrebEcKhgU86Kl0u"
      "name": "Science Officers",
      ... remaining Group key/value pairs ...
    },
    {
      "href" : "https://api.stormpath.com/v1/groups/Yu8ihas7HOpjHs3uhd7jGd"
      "name": "Security Team",
      ... remaining Group key/value pairs ...
    }
  ]
}

Search Groups

Group attributes supported for search:

  • name
  • description
  • status

Searchable Group Collection Resources

Group Collection Resource Search Functionality
/v1/directories/:directoryId/groups A search across groups in the specified directory.
/v1/applications/:applicationId/groups A search across groups accessible to the specified application.
/v1/accounts/:accountId/groups A search across groups assigned to the specified account.

Group Accounts

The Group accounts Collection for a Group Resource represents all accounts that are members of a specific group.

Group Accounts Collection Resource URI

/v1/groups/:groupId/accounts

Search Group Accounts

You may search for directories by sending a GET request to your application’s accounts Collection Resource href URL using search query parameters. Any matching directories with your tenant will be returned as a paginated list.

Searchable Account Attributes

The following account attributes are searchable via filter and attribute searches:

  • givenName
  • middleName
  • surname
  • username
  • email

In addition to the search query parameters, you may also use pagination and sorting query parameters to customize the paginated response. For example:

curl -u $API_KEY_ID:$API_KEY_SECRET \
     -H "Accept: application/json" \
     "https://api.stormpath.com/v1/groups/$GROUP_ID/accounts?q=foo&orderBy=surname&offset=0&limit=50"

Working With Group Accounts

Account resources support the full suite of CRUD commands and other interactions. Please see the Accounts section for more information.

Account Memberships

The accountMemberships Collection for a group Resource represents all account memberships where a specific group is a member. In this case, Account Memberships are simply an alternative, context-specific name for Group Memberships.

Account Memberships Collection Resource URI

/v1/groups/:groupId/accountMemberships

List Account Memberships

HTTP GET returns a Collection Resource containing the group memberships to which a specific group is a member.

Example Request

GET https://api.stormpath.com/v1/groups/smJGMBMpQ_-FKvMgCRTdVA/accountMemberships

Example Response

HTTP/1.1 200 OK
     Content-Type: application/json;charset=UTF-8;

{
    "href" : "https://api.stormpath.com/v1/groups/smJGMBMpQ_-FKvMgCRTdVA/accountMemberships",
    "offset" : 0,
    "limit" : 25,
    "items": [ {
          "href" : "https://api.stormpath.com/v1/groupMemberships/1u86fpQxJkFTfQHm1Hnhpb",
          "account" : {
                "href" : "https://api.stormpath.com/v1/accounts/gSraAOpFS-Savh3h6gFDzQ"
        },
        "group" : {
              "href" : "https://api.stormpath.com/v1/groups/smJGMBMpQ_-FKvMgCRTdVA"
        }
    }, {
        "href" : "https://api.stormpath.com/v1/groupMemberships/249Up9ojT6NUNEYocdG4Dj",
        "account" : {
              "href" : "https://api.stormpath.com/v1/accounts/k8idbaXRTSKncv3VLffDNw"
        },
        "group" : {
              "href" : "https://api.stormpath.com/v1/groups/smJGMBMpQ_-FKvMgCRTdVA"
        }
    } ]
}

Working With Account Memberships

Account Membership is a context-specific alias for a Group Membership. Group Membership resources support the full suite of CRUD commands and other interactions. Please see the Group Memberships section for more information.


Group Memberships

A Group Membership resource represents the link between an account and a group. When an Account is associated with a Group or a Group is associated with an Account, a group membership is created.

Group Membership Resource

Resource URI

v1/groupMemberships/:groupMembershipId

Resource Attributes

Attribute Description Type Valid Value
href The resource fully qualified location URI. String
account A link to the account of the group membership. Link
group A link to the group of the group membership. Link

For group memberships, you can:

Locate a Group Membership’s REST URL

When communicating with the Stormpath REST API, you might need to reference a group membership using the REST URL or href.

There are multiple ways to find a group membership’s href depending on what information you have available:

  • Retrieve a full list of group memberships for an account
  • Retrieve a full list of group members (as group membership pairings) for a group

In all cases, the process is fundamentally the same. Consider the first case as example. If you want to find a specific href for a group mapping on a specific account, you’ll need to search the group memberships for the associated account resource:

Example Request

curl -u $API_KEY_ID:$API_KEY_SECRET \
     -H "Accept: application/json" \
     "https://api.stormpath.com/v1/accounts/2dgfmriyAP238bkRB6ISmB/groupMemberships"

Example Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
    href: "https://api.stormpath.com/v1/accounts/2dgfmriyAP238bkRB6ISmB/groupMemberships"
    offset: 0
    limit: 25
    items: [1]
      0:  {
        href: "https://api.stormpath.com/v1/groupMemberships/2et4tXeMFFiMiZWUOIvWzj"
      - account: {
            href: "https://api.stormpath.com/v1/accounts/2dgfmriyAP238bkRB6ISmB"
        }
      - group: {
            href: "https://api.stormpath.com/v1/groups/cquoM06qa6pTkk1h2xOeJ"
          }
      }
}

If you know the name exactly, you can use an attribute search (e.g., “name=”) or, if you only know a small part, you can use a filter search (e.g., “q=My”) to narrow down the selection.

Create a Group Membership

To create a group membership you need the account and the group href.

Example Request

POST https://api.stormpath.com/v1/groupMemberships
    Content-Type: application/json;charset=UTF-8

{
  "account" : {
      "href" : "https://api.stormpath.com/v1/accounts/gSraAOpFS-Savh3h6gFDzQ"
   },
   "group" : {
       "href" : "https://api.stormpath.com/v1/groups/smJGMBMpQ_-FKvMgCRTdVA"
   }
}

Example Response

HTTP/1.1 201 Created
    Location: https://api.stormpath.com/v1/groupMemberships/57YZCqrNgrzcIGYs1PfP4F
    Content-Type: application/json;charset=UTF-8;

{
  "href" : "https://api.stormpath.com/v1/groupMemberships/57YZCqrNgrzcIGYs1PfP4F",
  "account" : {
      "href" : "https://api.stormpath.com/v1/accounts/gSraAOpFS-Savh3h6gFDzQ"
   },
   "group" : {
       "href" : "https://api.stormpath.com/v1/groups/smJGMBMpQ_-FKvMgCRTdVA"
   }
}

Retrieve a Group Membership

HTTP GET returns a representation of a groupMembership resource that includes the account and the group hrefs.

Example Request

GET https://api.stormpath.com/v1/groupMemberships/249Up9ojT6NUNEYocdG4Dj

Example Response

HTTP/1.1 200 OK
     Content-Type: application/json;charset=UTF-8;

{
 "href" : "https://api.stormpath.com/v1/groupMemberships/249Up9ojT6NUNEYocdG4Dj",
 "account" : {
   "href" : "https://api.stormpath.com/v1/accounts/k8idbaXRTSKncv3VLffDNw"
   },
  "group" : {
    "href" : "https://api.stormpath.com/v1/groups/smJGMBMpQ_-FKvMgCRTdVA"
   }
}

Expandable Resources

When retrieving an application, you can also retrieve one or more of its linked resources by expanding them in-line using the expand query parameter.

The following Application attributes are expandable:

  • account
  • group

See the Link Expansion section for more information on expanding link attributes.

Delete a Group Membership

Deleting a group membership completely erases the groupMembership resource from Stormpath. This operation does not delete the group or the account involved in the group membership, only the association between them.

Example Request

DELETE https://api.stormpath.com/v1/groupMemberships/57YZCqrNgrzcIGYs1PfP4F

Example Response

HTTP/1.1 204 No Content

List Group Memberships

You can list group memberships by account or group.

List Group Memberships For An Account

The account groupMemberships endpoint is a Collection Resource representing all group memberships where the account is involved.

/v1/accounts/:accountId/groupMemberships

HTTP GET returns a paginated list of the group memberships where the account is involved.

Example Request

GET https://api.stormpath.com/v1/accounts/MvdTIJakRO2Ry8c5z5itWw/groupMemberships

Example Response

HTTP/1.1 200 OK
     Content-Type: application/json;charset=UTF-8;

{
    "href" : "https://api.stormpath.com/v1/accounts/MvdTIJakRO2Ry8c5z5itWw/groupMemberships",
    "offset" : 0,
    "limit" : 25,
    "items" : [ {
          "href" : "https://api.stormpath.com/v1/groupMemberships/36KuRJcsfiHZjCR0Trv4yJ",
          "account" : {
                "href" : "https://api.stormpath.com/v1/accounts/MvdTIJakRO2Ry8c5z5itWw"
        },
        "group" : {
              "href" : "https://api.stormpath.com/v1/groups/tKP_30-9TcCneD3ktBwcig"
        }
    }, {
        "href" : "https://api.stormpath.com/v1/groupMemberships/1kjD3owGFAAzoGhFsO1oLz",
        "account" : {
              "href" : "https://api.stormpath.com/v1/accounts/MvdTIJakRO2Ry8c5z5itWw"
        },
        "group" : {
              "href" : "https://api.stormpath.com/v1/groups/smJGMBMpQ_-FKvMgCRTdVA"
        }
    } ]
}

List Account Memberships For A Group

The group accountMemberships endpoint is a [Collection Resource](#collections representing all group memberships where the group is involved.

/v1/groups/:groupId/accountMemberships

List Group Group Memberships (HTTP GET)

HTTP GET returns a paginated list of the group memberships where the group is involved.

Example Request

GET https://api.stormpath.com/v1/groups/smJGMBMpQ_-FKvMgCRTdVA/accountMemberships

Example Response

HTTP/1.1 200 OK
     Content-Type: application/json;charset=UTF-8;

{
    "href" : "https://api.stormpath.com/v1/groups/smJGMBMpQ_-FKvMgCRTdVA/accountMemberships",
    "offset" : 0,
    "limit" : 25,
    "items" : [
      {
          "href" : "https://api.stormpath.com/v1/groupMemberships/1u86fpQxJkFTfQHm1Hnhpb",
          "account" : {
              "href" : "https://api.stormpath.com/v1/accounts/gSraAOpFS-Savh3h6gFDzQ"
          },
          "group" : {
              "href" : "https://api.stormpath.com/v1/groups/smJGMBMpQ_-FKvMgCRTdVA"
          }
      },
      {
          "href" : "https://api.stormpath.com/v1/groupMemberships/249Up9ojT6NUNEYocdG4Dj",
          "account" : {
              "href" : "https://api.stormpath.com/v1/accounts/k8idbaXRTSKncv3VLffDNw"
          },
          "group" : {
              "href" : "https://api.stormpath.com/v1/groups/smJGMBMpQ_-FKvMgCRTdVA"
          }
      }
    ]
}

Accounts

An Account is a unique identity within a Directory, with a unique username and/or email address. An Account can log in to an Application using either the email address or username associated with it. Accounts can represent your end users (people), but they can also be used to represent services, daemons, processes, or any “entity” that needs to login to a Stormpath-enabled application. Additionally, an account may only exist in a single directory and may be in multiple groups owned by that directory. Accounts may not be assigned to groups within other directories.

It should be noted that the words ‘User’ and ‘Account’ usually mean the same thing, but there is a subtle difference that can be important at times:

  • An Account is a unique identity within a Directory. An account can exist in only a single directory but can be a part of multiple groups owned by that directory.
  • When an account is granted access to an application (by mapping a Directory or Group that contains the account to the application), it becomes a ‘User’ of that application.

Therefore an Account can be called a ‘User’ of an application if/when it can login to the application.

LDAP/AD Accounts

It should be noted that Accounts that originate in LDAP or Active Directory (AD) are mirrored in Stormpath. You cannot create, update or delete Accounts that originate in an LDAP mirrored directory – you can only read them or use them for login. This is because LDAP is the source of ‘truth’ and Stormpath does not (currently) have write-access to LDAP installations.

You manage LDAP/AD accounts on your primary LDAP/AD installation. LDAP/AD accounts and groups are automatically deleted when:

  • The backing object is deleted from the LDAP/AD directory service.
  • The backing LDAP/AD object information no longer matches the account filter criteria configured for the agent.
  • The LDAP/AD directory is deleted.

Account Resource

Resource URI

/v1/accounts/:accountId

Resource Attributes

Attribute Description Type Valid Value
href The resource fully qualified location URI String
username The username for the account. Must be unique across the owning directory. If not specified, the username will default to the email field. String 1 < N <= 255 characters
email The email address for the account. Must be unique across the owning directory. String 1 < N <= 255 characters
password The password for the account. Only include this attribute if setting or changing the account password. String 1 < N <= 255 characters
fullName The full name for the account holder. This is a computed attribute based on the givenName, middleName and surname attributes. It cannot be modified. To change this value, change one of the three respective attributes to trigger a new computed value. String
givenName The given (first) name for the account holder. String 1 < N <= 255 characters
middleName The middle (second) name for the account holder. String 1 < N <= 255 characters
surname The surname (last name) for the account holder. String 1 < N <= 255 characters
status enabled accounts are able to login to their assigned applications, disabled accounts may not login to applications, unverified accounts are disabled and have not verified their email address. Enum enabled,disabled,unverified
customData A link to the account’s customData resource that you can use to store your own account-specific custom fields. Link
groups A link to the groups that the account belongs to. Link
groupMemberships A link to the group memberships that the account belongs to. Link
directory A link to the account’s directory. Link
tenant A link to the tenant that owns the account’s directory. Link
emailVerificationToken A link to the account’s email verification token. This will only be set if the account needs to be verified. Link

For accounts, you can:

Locate an Account’s REST URL

In order to locate an account’s REST URL, you’ll need to first search for the account via either an application or a directory resource using specific information you have available.

For example, if you want to find the href for an account with the username “test” across an application, you’ll need to search the application for the “test” account object:

Example Request

curl -u $API_KEY_ID:$API_KEY_SECRET \
     -H "Accept: application/json" \
     "https://api.stormpath.com/v1/applications/5D1THHV76HO0EXPyxBXO8p/accounts?username=test"

Example Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
  "href": "https://api.stormpath.com/v1/applications/5D1THHV76HO0EXPyxBXO8p/accounts?username=test",
  "offset": 0,
  "limit": 25,
  "items" : [
    {
      "href" : "https://api.stormpath.com/v1/accounts/WpM9nyZ2TbaEzfbRvLk9KA",
      "username" : "test"
      ... remaining Account name/value pairs ...
    },
  ]
}

If you know the username exactly, you can use an attribute search (e.g., “username=”) or, if you only know a small part, you can use a filter search (e.g., “q=test”) to narrow down the selection.

Create an Account

Because Accounts are ‘owned’ by Directories, you create new accounts by adding them to a Directory. You can add an account to a directory directly or you can indirectly add an account to a Directory by registering an Account with an Application

This section will show examples using a Directory /accounts href, but they will function the same if you use an Application’s /accounts href as well.

You may only create accounts for Stormpath-manageed ‘Cloud’ directories. Mirrored accounts from LDAP or Active Directory must be created in the LDAP/AD server and they will be reflected in Stormpath accordingly. You cannot manually create accounts in a Mirrored directory.

Directory Accounts Resource URI

/v1/directories/:directoryId/accounts

Required Attributes

Optional Attributes

The password in the request is being sent to Stormpath as plain text. This is one of the reasons why Stormpath only allows requests via HTTPS. Stormpath implements the latest password hashing and cryptographic best-practices that are automatically upgraded over time so the developer does not have to worry about this. Stormpath can only do this for the developer if Stormpath receives the plaintext password so we can hash it using these techniques.

Plaintext passwords also allow Stormpath to enforce password restrictions in a configurable manner (e.g., you can configure your directories to reject passwords without mixed case and non-alphanumeric characters.)

Most importantly, Stormpath does not persist nor relay plaintext passwords in any circumstances.

On the client side, then, you do not need to worry about salting or storing passwords at any point; you need only pass them to Stormpath for hashing, salting, and persisting with the appropriate HTTPS API call (e.g., Create An Account or Update An Account).

Here are some account creation examples:

Simple creation request:

Example Request

POST https://api.stormpath.com/v1/directories/WpM9nyZ2TbaEzfbRvLk9KA/accounts
Content-Type: application/json;charset=UTF-8

{
  "username" : "jlpicard",
  "email" : "[email protected]",
  "givenName" : "Jean-Luc",
  "surname" : "Picard",
  "password" : "uGhd%a8Kl!"
}

Example Response

HTTP/1.1 201 Created
Location: https://api.stormpath.com/v1/accounts/cJoiwcorTTmkDDBsf02AbA
Content-Type: application/json;charset=UTF-8;

{
  "href" : "https://api.stormpath.com/v1/accounts/cJoiwcorTTmkDDBsf02AbA",
  "username" : "jlpicard",
  "email" : "[email protected]",
  "fullName" : "Jean-Luc Picard",
  "givenName" : "Jean-Luc",
  "middleName" : "",
  "surname" : "Picard",
  "status" : "UNVERIFIED",
  "customData": {
    "href": "https://api.stormpath.com/v1/accounts/cJoiwcorTTmkDDBsf02AbA/customData" 
  },
  "groups" : {
    "href" : "https://api.stormpath.com/v1/accounts/cJoiwcorTTmkDDBsf02AbA/groups"
  },
  "groupMemberships" : {
    "href" : "https://api.stormpath.com/v1/accounts/cJoiwcorTTmkDDBsf02AbA/groupMemberships"
  },
  "directory" : {
    "href" : "https://api.stormpath.com/v1/directories/WpM9nyZ2TbaEzfbRvLk9KA"
  },
  "tenant" : {
    "href" : "https://api.stormpath.com/v1/tenants/Ad8mIcavSty7XzD-xZdP3g"
  },
  "emailVerificationToken" : {
    "href" : "https://api.stormpath.com/v1/accounts/emailVerificationTokens/4VQxTP5I7Xio03QJTOwQy1"
  }
}

Create Directory Account with Custom Data

In addition to the Stormpath account attributes, you may also specify your own custom data by including a ‘customData’ JSON object:

curl -X POST --user $YOUR_API_KEY_ID:$YOUR_API_KEY_SECRET \
     -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -d '{
             "username" : "jlpicard",
             "email" : "[email protected]",
             "givenName" : "Jean-Luc",
             "middleName" : "",
             "surname" : "Picard",
             "password" : "uGhd%a8Kl!"
             "status" : "ENABLED",
             "customData": {
                 "rank": "Captain",
                 "birthDate": "2305-07-13",
                 "birthPlace": "La Barre, France",
                 "favoriteDrink": "Earl Grey tea"
             }
         }' \
     "https://api.stormpath.com/v1/directories/WpM9nyZ2TbaEzfbRvLk9KA/accounts"

Once created, you can further modify the custom data resource: delete it, add and remove attributes, etc as necessary. See the account custom data section for more information on custom data and custom data restrictions.

Create Directory Account and Suppress Registration Email

If you want to create a directory account and you want to override the directory’s account registration workflow email settings, you can specify a registrationWorkflowEnabled=false query parameter:

curl -X POST --user $YOUR_API_KEY_ID:$YOUR_API_KEY_SECRET \
     -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -d '{
           "username" : "jlpicard",
           "email" : "[email protected]",
           "givenName" : "Jean-Luc",
           "middleName" : "",
           "surname" : "Picard",
           "password" : "uGhd%a8Kl!"
           "status" : "ENABLED",
         }' \
     "https://api.stormpath.com/v1/directories/WpM9nyZ2TbaEzfbRvLk9KA/accounts?registrationWorkflowEnabled=false"

Retrieve an Account

HTTP GET returns a representation of an account resource that includes the attributes.

Example Request

GET https://api.stormpath.com/v1/accounts/cJoiwcorTTmkDDBsf02AbA

Example Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8;

{
  "href" : "https://api.stormpath.com/v1/accounts/cJoiwcorTTmkDDBsf02AbA",
  "username" : "jlpicard",
  "email" : "[email protected]",
  "fullName" : "Jean-Luc Picard",
  "givenName" : "Jean-Luc",
  "middleName" : "",
  "surname" : "Picard",
  "status" : "ENABLED",
  "customData": {
    "href": "https://api.stormpath.com/v1/accounts/cJoiwcorTTmkDDBsf02AbA/customData" 
  },
  "groups" : {
    "href" : "https://api.stormpath.com/v1/accounts/cJoiwcorTTmkDDBsf02AbA/groups"
  },
  "groupMemberships" : {
    "href" : "https://api.stormpath.com/v1/accounts/cJoiwcorTTmkDDBsf02AbA/groupMemberships"
  },
  "directory" : {
    "href" : "https://api.stormpath.com/v1/directories/1FaQ6kZxTL4DVJXWeXtUh7"
  },
  "tenant" : {
    "href" : "https://api.stormpath.com/v1/tenants/Ad8mIcavSty7XzD-xZdP3g"
  },
  "emailVerificationToken" : null
}

Expandable Resources

When retrieving an account, you can also retrieve one or more of its linked resources by expanding them in-line using the expand query parameter.

The following Account attributes are expandable:

  • customData
  • tenant
  • directory
  • groups
  • groupMemberships

Also, because groups and groupMemberships are Collection Resources themselves, you can additionally control pagination for either expanded collection. For example:

GET https://api.stormpath.com/v1/accounts/WpM9nyZ2TbaEzfbRvLk9KA?expand=tenant,directory,groups(offset:0,limit:50),groupMemberships(offset:0,limit:50)

See the Link Expansion section for more information on expanding link attributes.

Update an Account

Use HTTP POST when you want to change one or more specific attributes of an account resource. Unspecified attributes will not be changed, but at least one attribute must be specified.

Changes made to an account are immediately reflected in any application that has access to the account (based on applications’ account store mappings). Be careful updating an account for a single application’s needs - ensure that the changes are OK for any and all applications that may access the account.

Optional Attributes

The password in the request is being sent to Stormpath as plain text. This is one of the reasons why Stormpath only allows requests via HTTPS. Stormpath implements the latest password hashing and cryptographic best-practices that are automatically upgraded over time so the developer does not have to worry about this. Stormpath can only do this for the developer if Stormpath receives the plaintext password so we can hash it using these techniques.

Plaintext passwords also allow Stormpath to enforce password restrictions in a configurable manner (e.g., you can configure your directories to reject passwords without mixed case and non-alphanumeric characters.)

Most importantly, Stormpath does not persist nor relay plaintext passwords in any circumstances.

On the client side, then, you do not need to worry about salting or storing passwords at any point; you need only pass them to Stormpath for hashing, salting, and persisting with the appropriate HTTPS API call (e.g., Create An Account or Update An Account).

Here are some account update examples:

Example Request to Update the Name

POST https://api.stormpath.com/v1/accounts/cJoiwcorTTmkDDBsf02bAb
Content-Type: application/json;charset=UTF-8

{
  "username" : "jlpicard",
  "givenName" : "Jean-Luc",
  "surname" : "Picard",
}

Example Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8;

{
  "href" : "https://api.stormpath.com/v1/accounts/cJoiwcorTTmkDDBsf02AbA",
  "username" : "jlpicard",
  "email" : "[email protected]",
  "fullName" : "Jean-Luc Picard",
  "givenName" : "Jean-Luc",
  "middleName" : "",
  "surname" : "Picard",
  "status" : "ENABLED",
  "customData": {
    "href": "https://api.stormpath.com/v1/accounts/cJoiwcorTTmkDDBsf02AbA/customData" 
  },
  "groups" : {
    "href" : "https://api.stormpath.com/v1/accounts/cJoiwcorTTmkDDBsf02AbA/groups"
  },
  "groupMemberships" : {
    "href" : "https://api.stormpath.com/v1/accounts/cJoiwcorTTmkDDBsf02AbA/groupMemberships"
  },
  "directory" : {
    "href" : "https://api.stormpath.com/v1/directories/1FaQ6kZxTL4DVJXWeXtUh7"
  },
  "tenant" : {
    "href" : "https://api.stormpath.com/v1/tenants/Ad8mIcavSty7XzD-xZdP3g"
  },
  "emailVerificationToken" : null
}

Update an Account’s Password Directly

Example Request to Change an Account Password

POST https://api.stormpath.com/v1/accounts/cJoiwcorTTmkDDBsf02bAb
Content-Type: application/json;charset=UTF-8

{
  "password" : "L9%hw4c5q"
}

Example Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8;

{
  "href" : "https://api.stormpath.com/v1/accounts/cJoiwcorTTmkDDBsf02AbA",
  "username" : "jlpicard",
  "email" : "[email protected]",
  "fullName" : "Jean-Luc Picard",
  "givenName" : "Jean-Luc",
  "middleName" : "",
  "surname" : "Picard",
  "status" : "ENABLED",
  "customData": {
    "href": "https://api.stormpath.com/v1/accounts/cJoiwcorTTmkDDBsf02AbA/customData" 
  },
  "groups" : {
    "href" : "https://api.stormpath.com/v1/accounts/cJoiwcorTTmkDDBsf02AbA/groups"
  },
  "groupMemberships" : {
    "href" : "https://api.stormpath.com/v1/accounts/cJoiwcorTTmkDDBsf02AbA/groupMemberships"
  },
  "directory" : {
    "href" : "https://api.stormpath.com/v1/directories/1FaQ6kZxTL4DVJXWeXtUh7"
  },
  "tenant" : {
    "href" : "https://api.stormpath.com/v1/tenants/Ad8mIcavSty7XzD-xZdP3g"
  },
  "emailVerificationToken" : null
}

Assign an Account to a Group

If the account is part of a directory containing groups, you can associate the account with a group.

To assign an account to a group:

Example Request

POST https://api.stormpath.com/v1/groupMemberships
Content-Type: application/json;charset=UTF-8

{
  "account" : {
    "href" : "https://api.stormpath.com/v1/accounts/Gu8oshf7HdsspjHs3uhd7jGd"
  },
  "group" : {
    "href" : "https://api.stormpath.com/v1/groups/ZgoHUG0oSoVNeU0K4GZeVQ"
  }
}

Example Response

HTTP/1.1 201 Created
Location: https://api.stormpath.com/v1/groupMemberships/cJoiwjorTTmLDDBsf04Abi
Content-Type: application/json;charset=UTF-8;

{
  "href" : "https://api.stormpath.com/v1/groupMemberships/cJoiwjorTTmLDDBsf04Abi",
  "account" : {
    "href" : "https://api.stormpath.com/v1/accounts/Gu8oshf7HdsspjHs3uhd7jGd"
  },
  "group" : {
    "href" : "https://api.stormpath.com/v1/groups/ZgoHUG0oSoVNeU0K4GZeVQ"
  }
}

Remove an Account from a Group

If the account is the member of a group within a directory, you can remove the account from the group by deleting the groupMembership resource that associates the two together:

Example Request

DELETE https://api.stormpath.com/v1/groupMemberships/cJoiwjorTTmLDDBsf04Abi

Example Response

HTTP/1.1 204 No Content

Enable or Disable an Account

Accounts have an “status” which defines its state in the systems: enabled and disabled. An enabled account can be successfully authenticated if it is assigned to an active account store in an application while a disabled account cannot.

Enabling and disabling accounts for mirrored (LDAP) directories is not available in Stormpath. You manage mirrored (LDAP) accounts on the primary server installation.

For example, to enable an account:

Example Request

POST https://api.stormpath.com/v1/accounts/cJoiwcorTTmkDDBsf02bAb
Content-Type: application/json;charset=UTF-8

{
  "status" : "ENABLED"
}

Delete an Account

Deleting an account completely erases the account from the directory and erases all account information from Stormpath.

Deleting an account permanently removes the account from any application that has access to the account (based on applications’ account store mappings). Additionally, be careful deleting an account for a single application’s needs - ensure that the deletion is OK for any and all applications that may access the account.

To delete an account:

Example Request

DELETE https://api.stormpath.com/v1/accounts/cJoiwcorTTmkDDBsf02bAb

Example Response

HTTP/1.1 204 No Content

Account Custom Data

While Stormpath’s default Account attributes are useful to many applications, you might want to add your own custom data to a Stormpath account. If you want, you can store all of your custom account information in Stormpath so you don’t have to maintain another separate database to store your specific account data.

Please see the custom data section for more information and requirements/restrictions for creating, retrieving, updating and deleting account custom data.

List Accounts

The accounts resource is a Collection Resource that represents all accounts associated with their parent. There are different endpoints that can list their associated accounts. Using the API, you can access:

Search Accounts

Account attributes supported for search:

  • givenName
  • surname
  • email
  • username
  • middleName
  • status

Searchable Account Collection Resources

Account Collection Resource Search Functionality
/v1/directories/:directoryId/accounts A search across accounts in the specified directory.
/v1/applications/:applicationId/accounts A search across accounts that are users of the specified application.
/v1/groups/:groupId/accounts A search across accounts in the specified group.

Verify An Email Address

If you want to verify that an account’s email address is valid that the account belongs to a real person, Stormpath can help automate this for you, too.

Understanding The Email Verification Workflow

This workflow requires 3 parties to be involved: your application end-user, your application, and the Stormpath API server.

  1. When the account is created in a Directory that has “Verification” enabled, Stormpath will email the account email address automatically.
  2. The end-user opens his or her email and clicks the verification link.
  3. With the token from the verification link clicked by the end-user, Your application calls back to the Stormpath API server to complete the process.

As mentioned previously, when you create a new account, it is stored in a Directory. If the account is created in a directory with both Account Registration and Verification enabled, Stormpath will automatically send a welcome email that contains a verification link to the account’s email address on your behalf. If the person reading the email clicks the verification link in the email, the account will then have an ENABLED status and be allowed to login to applications.

Accounts created in a Directory that has the Verification workflow enabled will have an UNVERIFIED status by default. UNVERIFIED is the same as DISABLED, but additionally indicates why the account is disabled. When the email link is clicked, they will have an ENABLED status.

The Account Verification Base URL

It is also expected that the workflow’s Account Verification Base URL has been set to a URL that will be processed by your own application web server. This URL should be free of any query parameters, as the Stormpath back-end will append on to the URL a parameter used to verify the email. If this URL is not set, a default Stormpath-branded page will appear which allows the user to complete the workflow.

The Account Verification Base URL defaults to a Stormpath API Sever URL which, while it is functional, is a Stormpath API server web page. Because it will likely confuse your application end-users if they see a Stormpath web page, we strongly recommended that you specify a URL that points to your web application. Moreover, when specifying the Base URL, ensure it is a Base URL without query parameters

Configure The Verification Workflow

This workflow is disabled by default on Directories, but you can enable it, and set up the account verification base URL, easily in the Stormpath Admin Console UI. Refer to the Stormpath Admin Console product guide for complete instructions.

Trigger The Verification Email (Create A Token)

In order to verify an account’s email address, an emailVerificationToken must be created for that account. To create this token, you simply create an account in a directory, either programmatically or via a public account creation form of your own design, that has the account registration and verification workflow enabled.

For example, if you were to request the account object for a user who has not yet been verified, you will note that the account status is set to UNVERIFIED and emailVerificationToken will have an href:

{
  href: "https://api.stormpath.com/v1/accounts/6XLbNaUsKm3E0kXMTTr10V",
  username: "testuser",
  email: "[email protected]",
  fullName: "test user",
  givenName: "test",
  surname: "user",
  status: "UNVERIFIED",
  groups: {
    href: "https://api.stormpath.com/v1/accounts/6XLbNaUsKm3E0kXMTTr10V/groups"
  },
  groupMemberships: {
    href: "https://api.stormpath.com/v1/accounts/6XLbNaUsKm3E0kXMTTr10V/groupMemberships"
  },
  directory: {
    href: "https://api.stormpath.com/v1/directories/5D1bvO5To6KQBaGFh793Zz"
  },
  tenant: {
    href: "https://api.stormpath.com/v1/tenants/23mq7BPIxNgPUPZDwj04SZ"
  },
  emailVerificationToken: {
    href: "https://api.stormpath.com/v1/accounts/emailVerificationTokens/6YJv9XBH1dZGP5A8rq7Zyl"
  }
}

As an end-developer, all you need to do to create email verification tokens when a new account is created is to configure the workflow for the appropriate directory.

Verifying The Account (Consume The Token)

When a new account is registered after configuration, either programmatically or through an account creation form in your application, an email verification token is created and Stormpath then automatically sends an email to the user. This email will include a link to the base URL you’ve configured with the following query string parameter:

http://www.yourapplicationurl.com/path/to/validator?sptoken=$VERIFICATION_TOKEN

The token you capture from the query string is used to form the full href for a special email verification endpoint used to verify the account.

Email Verification Tokens Collection Resource URI

/v1/accounts/emailVerificationsToken/:verificationToken

To verify the account, you use the token from the query string to form the above URL and POST a body-less request against the fully-qualified end point:

Example Request

POST https://api.stormpath.com/v1/accounts/emailVerificationTokens/6YJv9XBH1dZGP5A8rq7Zyl

Example Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8;

{
  href: "https://api.stormpath.com/v1/accounts/6XLbNaUsKm3E0kXMTTr10V"
}

If the validation succeeds, you will receive back the href for the account resource which has now been verified. An email confirming the verification will be automatically sent to the account’s email address by Stormpath afterwards, and the account will then be able to authenticate successfully.

If the verification token is not found, a 404 Not Found is returned with an error payload explaining why the attempt failed:

Example Email Verification Failure Response

HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8;

{
  status: 404
  code: 404
  message: "The requested resource does not exist."
  developerMessage: "The requested resource does not exist."
  moreInfo: "mailto:[email protected]"
}

Authenticate An Account

After an account has been created, you can authenticate an account given an input of a username or email and a password from the end-user. When authentication occurs, you are authenticating a user within a specific application against the application’s account stores. That being said, the application resource is the starting point for authentication attempts.

Once you have the application resource you may attempt authentication by sending a ‘POST’ request to the application’s loginAttempts endpoint and providing a base64 encoded username and password pair that is seperated with a colon (for example – testuser:testpassword). Stormpath requires that the username and password are base64 encoded so these values are not passed as clear text.

Example Request

POST https://api.stormpath.com/v1/applications/WpM9nyZ2TbaEzfbRvLk9KA/loginAttempts
Content-Type: application/json;charset=UTF-8

{
   "type": "basic",
   "value": "anNtaXRoOmNoYW5nZW1l"
}

Example Successful Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8;

{
  "account": {
    "href" : "https://api.stormpath.com/v1/accounts/5BedLIvyfLjdKKEEXAMPLE"
  }
}

For more information on working with applications and authentication, refer to the Log in (Authenticate) an Account section of this guide.

Reset An Account’s Password

This is a self-service password reset workflow. The account is sent an email with a secure link. The person owning the account can click on the link and be shown a password reset form to reset their password. This is strongly recommended to reduce support requests to your application team as well as to reduce your exposure to account passwords for added security.

The password reset workflow involves changes to an account at an application level, and as such, this workflow relies on the application resource as a starting point. For more information on working with this workflow via REST after they have already been configured, refer to the Working With Applications section of this guide.

This workflow is disabled by default for accounts, but you can enable it easily in the Stormpath Admin Console UI. Refer to the Stormpath Admin Console product guide for complete instructions.

Workflows are only available on cloud directories and only configurable using the Stormpath Admin Console. They are not currently configurable via the REST API. Also, the Stormpath Administrator directory’s automated workflows cannot be altered.

Account Groups

The account’s groups resource is a Collection Resource which represents all groups where a specific account is a member.

Resource URI

/v1/accounts/:accountId/groups

List Account Groups

HTTP GET returns a Collection Resource containing links for all groups where a specific account is a member.

Example Request

GET https://api.stormpath.com/v1/accounts/cJoiwcorTTmkDDBsf02AbA/groups

Example Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8;

{
  "href": "https://api.stormpath.com/v1/accounts/cJoiwcorTTmkDDBsf02AbA/groups"
  "offset": 0,
  "limit": 25,
  "items" : [
    {
      "href" : "https://api.stormpath.com/v1/groups/ZgoHUG0oSoVNeU0K4GZeVQ"
      "name": "Red Shirts",
      "description": "",
      "status": "ENABLED",
      "directory": {
        "href": "http://api.stormpath.com/v1/directories/1FaQ6kZxTL4DVJXWeXtUh7"
      },
      "tenant": {
        "href": "http://api.stormpath.com/v1/tenants/tqjB6LiESGO00qvC5dkNw"
      },
      "accounts": {
        "href": "http://api.stormpath.com/v1/groups/ZgoHUG0oSoVNeU0K4GZeVQ/accounts"
      },
      "accountMemberships": {
        "href": "http://api.stormpath.com/v1/groups/ZgoHUG0oSoVNeU0K4GZeVQ/accountMemberships"
      }
    },
    ... additional Account resources ...
  ]
}

Search Account Groups

You may search for directories by sending a GET request to your application’s accounts Collection Resource href URL using search query parameters. Any matching directories with your tenant will be returned as a paginated list.

Searchable Group Attributes

The following group attributes are searchable via filter and attribute searches:

  • name
  • description
  • status

In addition to the search query parameters, you may also use pagination and sorting query parameters to customize the paginated response. For example:

curl -u $API_KEY_ID:$API_KEY_SECRET \
     -H "Accept: application/json" \
     "https://api.stormpath.com/v1/accounts/$ACCOUNT_ID/groups?q=foo&orderBy=name&offset=0&limit=50"

Working With Account Groups

Group resources support the full suite of CRUD commands and other interactions. Please see the Groups section for more information.

Account Group Memberships

An account’s groupMemberships resource is a Collection Resource which represents all group memberships where a specific account is a member.

Account Group Membership Collection Resource URI

/v1/accounts/:accountId/groupMemberships

List Account Group Memberships

HTTP GET returns a Collection Resource containing the group memberships to which a specific account is a member.

Example Request

GET https://api.stormpath.com/v1/accounts/MvdTIJakRO2Ry8c5z5itWw/groupMemberships

Example Response

HTTP/1.1 200 OK
     Content-Type: application/json;charset=UTF-8;

{
    "href" : "https://api.stormpath.com/v1/accounts/MvdTIJakRO2Ry8c5z5itWw/groupMemberships",
    "offset" : 0,
    "limit" : 25,
    "items": [
      {
        "href" : "https://api.stormpath.com/v1/groupMemberships/36KuRJcsfiHZjCR0Trv4yJ",
        "account" : {
          "href" : "https://api.stormpath.com/v1/accounts/MvdTIJakRO2Ry8c5z5itWw"
        },
        "group" : {
          "href" : "https://api.stormpath.com/v1/groups/tKP_30-9TcCneD3ktBwcig"
        }
      },
      {
        "href" : "https://api.stormpath.com/v1/groupMemberships/1kjD3owGFAAzoGhFsO1oLz",
        "account" : {
          "href" : "https://api.stormpath.com/v1/accounts/MvdTIJakRO2Ry8c5z5itWw"
        },
        "group" : {
          "href" : "https://api.stormpath.com/v1/groups/smJGMBMpQ_-FKvMgCRTdVA"
        }
      }
    ]
}

Working With Account Group Memberships

Groups Membership resources support the full suite of CRUD commands and other interactions. Please see the Group Memberships section for more information.


Custom Data

Account and Group resources have predefined fields that are useful to many Applications, but you are likely to have your own custom data that you need to associate with an account or group as well.

For this reason, both the account and group resources support a linked customData resource that you can use for your own needs.

The customData resource is a schema-less JSON object (aka ‘map’, ‘associative array’, or ‘dictionary’) that allows you to specify whatever name/value pairs you wish.

The customData resource href is always the account or group href with a /customData suffix:

Account Custom Data Resource URI

/v1/accounts/:accountId/customData

Group Custom Data Resource URI

/v1/groups/:groupId/customData

In addition to your custom name/value pairs, a customData resource will always contain 3 reserved read-only fields:

  • href: The fully qualified location of the custom data resource
  • createdAt: the UTC timestamp with millisecond precision of when the resource was created in Stormpath as an ISO 8601 formatted string, for example 2017-04-01T14:35:16.235Z
  • modifiedAt: the UTC timestamp with millisecond precision of when the resource was last updated in Stormpath as an ISO 8601 formatted string.

You can store an unlimited number of additional name/value pairs in the customData resource, with the following restrictions:

  • The total storage size of a single customData resource cannot exceed 10 MB (megabytes). The href, createdAt and modifiedAt field names and values do not count against your resource size quota.
  • Field names must:
    • be 1 or more characters long, but less than or equal to 255 characters long (1 <= N <= 255).
    • contain only alphanumeric characters 0-9A-Za-z, underscores _ or dashes - but cannot start with a dash -.
    • may not equal any of the following reserved names: href, createdAt, modifiedAt, meta, spMeta, spmeta, ionmeta, or ionMeta.

While the meta, spMeta, spmeta, ionmeta, or ionMeta fields are not returned in the response today, they might be used in the future. As is the case with all JSON use cases, ensure your REST client will not break if it encounters one of these (or other fields it does not recognize) at some time in the future.

For Custom Data, you can:

Create Custom Data

Whenever you create an account or a group, an empty customData resource is created for that account or group automatically – you do not need to explicitly execute a request to create it.

However, it is often useful to populate custom data at the same time you create an account or group. You can do this by embedding the customData directly in the account or group resource. For example:

Example Create Account with Custom Data

curl -X POST --user $YOUR_API_KEY_ID:$YOUR_API_KEY_SECRET \
     -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -d '{
           "username" : "jlpicard",
           "email" : "[email protected]",
           "givenName" : "Jean-Luc",
           "middleName" : "",
           "surname" : "Picard",
           "password" : "uGhd%a8Kl!"
           "status" : "ENABLED",
           "customData": {
             "rank": "Captain",
             "birthDate": "2305-07-13",
             "birthPlace": "La Barre, France",
             "favoriteDrink": "Earl Grey tea"
           }
         }' \
 "https://api.stormpath.com/v1/directories/exampleDirectoryId/accounts"

Example Create Group with Custom Data

 curl -X POST --user $YOUR_API_KEY_ID:$YOUR_API_KEY_SECRET \
      -H "Accept: application/json" \
      -H "Content-Type: application/json" \
      -d '{
            "name" : "Starfleet Officers",
            "customData": {
              "headquarters": "San Francisco, CA"
            }
          }' \
  "https://api.stormpath.com/v1/directories/exampleDirectoryId/groups"

Retrieve Custom Data

A common way to retrieve an account or group’s custom data is to use link expansion and retrieve the custom data at the same time as when you retrieve an account or group.

Example: Retrieve an Account with its Custom Data

curl --user $YOUR_API_KEY_ID:$YOUR_API_KEY_SECRET https://api.stormpath.com/v1/accounts/exampleAccountId?expand=customData

Example: Retrieve a Group with its Custom Data

curl --user $YOUR_API_KEY_ID:$YOUR_API_KEY_SECRET https://api.stormpath.com/v1/groups/exampleGroupId?expand=customData

You can also of course return an account or group’s custom data resource by executing a GET request directly to the account-specific or group-specific Custom Data Resource URI.

Example Retrieve Account Custom Data Request

curl --user $YOUR_API_KEY_ID:$YOUR_API_KEY_SECRET https://api.stormpath.com/v1/accounts/exampleAccountId/customData

Example Retrieve Group Custom Data Request

curl --user $YOUR_API_KEY_ID:$YOUR_API_KEY_SECRET https://api.stormpath.com/v1/groups/exampleGroupId/customData

Example Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8;

{
  "href": "https://api.stormpath.com/v1/accounts/cJoiwcorTTmkDDBsf02AbA/customData",
  "createdAt": "2014-07-16T13:48:22.378Z",
  "modifiedAt": "2014-07-16T13:48:22.378Z",
  "birthDate": "1985-07-15",
  "favoriteColor": "blue",
}

Update Custom Data

You may update an account or group’s custom data, in one of two ways:

Update Custom Data Directly

The first way to update an account or group’s custom data is by POSTing changes directly to the custom data’s href. This allows you to interact with the customData resource directly, without having to do so ‘through’ an account or group request.

In the following example request, we’re interacting with a customData resource directly, and we’re changing the value of an existing field named favoriteColor and we’re adding a brand new field named hobby:

Example Account Custom Data Update

curl -X POST --user $YOUR_API_KEY_ID:$YOUR_API_KEY_SECRET \
     -H "Accept: application/json" \
     -H "Content-Type: application/json;charset=UTF-8" \
     -d '{
           "favoriteColor": "red",
           "hobby": "Kendo"
         }' \
  "https://api.stormpath.com/v1/accounts/cJoiwcorTTmkDDBsf02bAb/customData"

The response will contain the resource with the latest values:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8;

{
  "href": "https://api.stormpath.com/v1/accounts/cJoiwcorTTmkDDBsf02AbA/customData",
  "createdAt": "2014-07-16T13:48:22.378Z",
  "modifiedAt": "2014-07-16T13:48:22.378Z",
  "birthDate": "1985-07-15",
  "favoriteColor": "red",
  "hobby": "Kendo"
}

As you can see, the response contains the ‘merged’ representation of what was already on the server plus what was sent in the request, and at no point did we need to interact with the account directly.

Update Custom Data as part of an Account or Group Request

Sometimes it is helpful to update an account or group’s customData as part of an update request for the account or group. In this case, just submit customData changes in an embedded customData field embedded in the account or group request resource. For example:

curl -X POST --user $YOUR_API_KEY_ID:$YOUR_API_KEY_SECRET \
     -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -d '{
           "status" : "ENABLED",
           "customData": {
               "favoriteColor": "blue",
               "hobby": "Kendo"
           }
         }' \
    "https://api.stormpath.com/v1/accounts/exampleAccountId"

In the above example, we’re performing 3 modifications in one request:

  1. We’re modifying the account’s status attribute and setting it to ENABLED. We’re also
  2. Changing the existing customData favoriteColor field value to blue (it was previously red) and
  3. Adding a new customData hobby field with a value of Kendo.

This request modifies both the account resource and that account’s custom data in a single request.

The same simultaneous update behavior may be performed for Group updates as well.

Delete Custom Data

You may delete all of an account or group’s custom data by sending a DELETE request to the account or group’s customData href:

Example: Delete all of an Account’s Custom Data

curl --user $YOUR_API_KEY_ID:$YOUR_API_KEY_SECRET https://api.stormpath.com/v1/accounts/exampleAccountId/customData

Example: Delete all of a Group’s Custom Data

curl --user $YOUR_API_KEY_ID:$YOUR_API_KEY_SECRET https://api.stormpath.com/v1/groups/exampleGroupId/customData

Example Response

HTTP/1.1 204 No Content

This will delete all of the respective account or group’s custom data fields, but it leaves the customData placeholder in the account or group resource. You cannot delete the customData resource entirely – it will be automatically permanently deleted when the account or group is deleted.

Delete Custom Data Field

You may also delete an individual custom data field entirely.

To understand field deletion, we should have a quick reminder about JSON null values. null is a valid value for JSON fields and may be specified. For example:

curl -X POST --user $YOUR_API_KEY_ID:$YOUR_API_KEY_SECRET \
     -H "Accept: application/json" \
     -H "Content-Type: application/json;charset=UTF-8" \
     -d '{
           "favoriteColor": null
         }' \
  "https://api.stormpath.com/v1/accounts/cJoiwcorTTmkDDBsf02bAb/customData"

This request is valid and indicates that the favoriteColor field still exists on the customData resource, and it is a meaningful field, it just does not currently have a value (maybe it will be populated later).

Because null is an important and often useful value for JSON data, then, we can’t delete a field (remove it entirely from the customData resource) by simply setting it to null.

Therefore, to delete a customData field, we must send an explicit DELETE request to an href representing the exact field to delete, using the following resource URI:

Account Custom Data Field Resource URI

https://api.stormpath.com/v1/accounts/:accountId/customData/:fieldName

Group Custom Data Field Resource URI

https://api.stormpath.com/v1/groups/:groupId/customData/:fieldName

These URIs only supports DELETE requests.

Example Request

DELETE https://api.stormpath.com/v1/accounts/cJoiwcorTTmkDDBsf02bAb/customData/favoriteColor

Example Response

HTTP/1.1 204 No Content

This request would remove the favoriteColor field entirely from the customData resource. The next time the resource is retrieved, the field will be missing entirely.


Integrating with Google

Stormpath supports accessing accounts from a number of different locations including Google. Google uses OAuth 2.0 protocol for authentication / authorization and Stormpath can leverage their authorization codea (or access tokens) to return an Account for a given code.

The steps to enable this functionality into your application include:

Google Directories follow behavior similar to mirror directories, but have a Provider resource that contains information regarding the Google application that the directory is configured for.

Google Provider Resource

A provider resource holds specific information needed for working with a Google Directory. It is important to understand the format of the provider resource when creating and updating a Google Directory.

A provider resource can be obtained by accessing the directory’s provider with an HTTP GET as follows:

Example Request

GET https://api.stormpath.com/v1/directories/bckhcGMXQDujIXpbCDRb2Q/provider

Example Response

{
    "clientId": "501417", 
    "clientSecret": "4913953281ec6bb109", 
    "redirectUri": "https://myapp.com/google/authentication"
    "createdAt": "2014-03-31T21:01:34.631Z", 
    "href": "https://api.stormpath.com/v1/directories/bckhcGMXQDujIXpbCDRb2Q/provider", 
    "modifiedAt": "2014-03-31T21:01:34.643Z", 
    "providerId": "google"
}

Resource Attributes

Attribute Description Type Valid Value
clientId The App ID for your Google application String
clientSecret The App Secret for your Google application String
redirectUri The redirection Uri for your Google application String
providerId The provider ID is the Stormpath ID for the Directory’s account provider String ‘google’

In addition to your application specific attributes, a Provider resource will always contain 3 reserved read-only fields:

  • href : The fully qualified location of the custom data resource
  • createdAt : the UTC timestamp with millisecond precision of when the resource was created in Stormpath as an ISO 8601 formatted string
  • modifiedAt : the UTC timestamp with millisecond precision of when the resource was created in Stormpath as an ISO 8601 formatted string

Creating a Google Directory

Creating a Google Directory requires that you gather some information beforehand from Google’s Developer Console regarding your application.

  • Client ID
  • Client Secret
  • Redirect URI

Creating a Google Directory is very similar to creating a directory within Stormpath by making a HTTP POST request to the /v1/directories endpoint. For a Google Directory to be configured correctly, you must specify the correct Provider information.

Example Request

curl -X POST --user $YOUR_API_KEY_ID:$YOUR_API_KEY_SECRET \
     -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -d '{
          "name" : "my-google-directory",
          "description" : "A Google directory",
          "provider": {
            "providerId": "google",
            "clientId":"857385-m8vk0fn2r7jmjo.apps.googleusercontent.com",
            "clientSecret":"ehs7_-bA7OWQSQ4",
            "redirectUri":"https://myapplication.com/authenticate"
          }
        }' \
 "https://api.stormpath.com/v1/directories?expand=provider"

Example Response

HTTP/1.1 201 Created
Location: https://api.stormpath.com/v1/directories/bckhcGMXQDujIXpbCDRb2Q
Content-Type: application/json;charset=UTF-8;

{
    "accounts": {
        "href": "https://api.stormpath.com/v1/directories/bckhcGMXQDujIXpbCDRb2Q/accounts"
    }, 
    "description": "A Google directory", 
    "groups": {
        "href": "https://api.stormpath.com/v1/directories/bckhcGMXQDujIXpbCDRb2Q/groups"
    }, 
    "href": "https://api.stormpath.com/v1/directories/bckhcGMXQDujIXpbCDRb2Q", 
    "name": "my-google-directory", 
    "provider": {
        "clientId": "857385-m8vk0fn2r7jmjo.apps.googleusercontent.com", 
        "clientSecret": "ehs7_-bA7OWQSQ4", 
        "createdAt": "2014-03-31T23:47:05.576Z", 
        "href": "https://api.stormpath.com/v1/directories/bckhcGMXQDujIXpbCDRb2Q/provider", 
        "modifiedAt": "2014-03-31T23:47:05.592Z", 
        "providerId": "google", 
        "redirectUri": "https://myapplication.com/authenticate"
    }, 
    "status": "ENABLED", 
    "tenant": {
        "href": "https://api.stormpath.com/v1/tenants/bckhcGMXQDujIXpbCDRb2Q"
    }
}

After the Google Directory has been created, it needs to be mapped with an application as an account store. The Google Directory cannot be a default account store or a default group store. Once the directory is mapped as an account store for an application, you are ready to access Accounts with Google Authorization Codes.

Accessing Accounts with Google Authorization Codes or an Access Tokens

To access or create an account in an already created Google Directory, it is required to gather a Google Authorization Code on behalf of the user. This requires leveraging Google’s OAuth 2.0 protocol and the user’s consent for your application’s permissions.

Once the Authorization Code is gathered, you can get or create the Account by HTTP POSTing to the Application accounts collection and specifying the providerData JSON object. The providerData JSON object specifies the type of provider and the authorization code as follows:

{
  "providerId": "google",
  "code": "%ACCESS_CODE_FROM_GOOGLE%"
}

The following is how you use providerData to get an Account for a given authorization code:

Example Request

curl -X POST --user $YOUR_API_KEY_ID:$YOUR_API_KEY_SECRET \
     -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -d '{
            "providerData": {
              "providerId": "google",
              "code": "4/2Dz0r7r9oNBE9dFD-_JUb.suCu7uj8TEnp6UAPm0"
            }
          }' \
 "https://api.stormpath.com/v1/applications/24mp4us71ntza6lBwlu/accounts"

Example Response

HTTP/1.1 201 Created
Location: https://api.stormpath.com/v1/accounts/m0fw8GvxpM7n3pw6tyw9
Content-Type: application/json;charset=UTF-8;

{
    "customData": {
        "href": "https://api.stormpath.com/v1/accounts/m0fw8GvxpM7n3pw6tyw9/customData"
    },
    "directory": {
        "href": "https://api.stormpath.com/v1/directories/U0HJ7YcCeMpRfMcRT8ph"
    },
    "email": "[email protected]",
    "emailVerificationToken": null,
    "fullName": "Test User",
    "givenName": "Test",
    "groupMemberships": {
        "href": "https://api.stormpath.com/v1/accounts/m0fw8GvxpM7n3pw6tyw9/groupMemberships"
    },
    "groups": {
        "href": "https://api.stormpath.com/v1/accounts/m0fw8GvxpM7n3pw6tyw9/groups"
    },
    "href": "https://api.stormpath.com/v1/accounts/m0fw8GvxpM7n3pw6tyw9",
    "middleName": null,
    "providerData": {
        "href": "https://api.stormpath.com/v1/accounts/m0fw8GvxpM7n3pw6tyw9/providerData"
    },
    "status": "ENABLED",
    "surname": "User",
    "tenant": {
        "href": "https://api.stormpath.com/v1/tenants/GPpLzIzYkOO68I9i4dx"
    },
    "username": "testuser"
}

The HTTP Status code when accessing an account based on a Google Authorization Code will denote if the account was created (201) or if it already existed in the Google Directory (200)

To expand the providerData to get the Access Token for the Account in one HTTP request, add expand=providerData to the URL query parameters.

Once an Account is retreived, Stormpath maps common fields for the Google User to the Account. The access token and the refresh token for any additional calls in the providerData resource and can be retreived by:

GET https://api.stormpath.com/v1/accounts/m0fw8GvxpM7n3pw6tyw9/providerData

The returned providerData will include:

{
  "accessToken": "y29.1.AADN_Xo2hxQflWwsgCSK-WjSw1mNfZiv4", 
  "createdAt": "2014-04-01T17:00:09.154Z", 
  "href": "https://api.stormpath.com/v1/accounts/ciYmtETytH0tbHRBas1D5/providerData", 
  "modifiedAt": "2014-04-01T17:00:09.189Z", 
  "providerId": "google", 
  "refreshToken": "1/qQTS638g3ArE4U02FoiXL1yIh-OiPmhc"
}

The accessToken can also be passed as a field for the providerData to access the account once it is retrieved

POST https://api.stormpath.com/v1/applications/24mp4us71ntza6lBwlu/accounts
Content-Type: application/json;charset=UTF-8

{
  providerData: {
    "providerId": "google",
    "accessToken":"y29.1.AADN_Xo2hxQflWwsgCSK-WjSw1mNfZiv4"
  }
}

The refreshToken will only be present if your application asked for offline access. Review Google’s documentation for more information regarding OAuth offline access.


Integrating with Facebook

Stormpath supports accessing accounts from a number of different locations including Facebook. Facebook uses OAuth 2.0 protocol for authentication / authorization and Stormpath can leverage their or access tokens to return an Account for a given code.

The steps to enable this functionality into your application include:

Facebook Directories follow behavior similar to mirror directories, but have a Provider resource that contains information regarding the Google application that the directory is configured for.

Facebook Provider Resource

A provider resource holds specific information needed for working with a Facebook Directory. It is important to understand the format of the provider resource when creating and updating a Facebook Directory.

A provider resource can be obtained by accessing the directory’s provider with an HTTP GET as follows:

Example Request

GET https://api.stormpath.com/v1/directories/bckhcGMXQDujIXpbCDRb2Q/provider

Example Response

{
    "clientId": "501417", 
    "clientSecret": "4913953281ec6bb109", 
    "redirectUri": "https://myapp.com/google/authentication"
    "createdAt": "2014-03-31T21:01:34.631Z", 
    "href": "https://api.stormpath.com/v1/directories/bckhcGMXQDujIXpbCDRb2Q/provider", 
    "modifiedAt": "2014-03-31T21:01:34.643Z", 
    "providerId": "facebook"
}

Resource Attributes

Attribute Description Type Valid Value
clientId The App ID for your Google application String
clientSecret The App Secret for your Google application String
providerId The provider ID is the Stormpath ID for the Directory’s account provider String ‘facebook’

In addition to your application specific attributes, a Provider resource will always contain 3 reserved read-only fields:

  • href : The fully qualified location of the custom data resource
  • createdAt : the UTC timestamp with millisecond precision of when the resource was created in Stormpath as an ISO 8601 formatted string
  • modifiedAt : the UTC timestamp with millisecond precision of when the resource was created in Stormpath as an ISO 8601 formatted string

Creating a Facebook Directory

Creating a Facebook Directory requires that you gather some information beforehand from Facebook’s Developer Console regarding your application.

  • Client ID
  • Client Secret

Creating a Facebook Directory is very similar to creating a directory within Stormpath by making a HTTP POST request to the /v1/directories endpoint. For a Facebook Directory to be configured correctly, you must specify the correct Provider information.

Example Request

curl -X POST —user $YOUR_API_KEY_ID:$YOUR_API_KEY_SECRET \

 -H "Accept: application/json" \
 -H "Content-Type: application/json" \
 -d '{
        "name" : "my-facebook-directory",
        "description" : "A Facebook directory",
        "provider": {
          "providerId": "facebook",
          "clientId":"857385m8vk0fn2r7jmjo",
          "clientSecret":"ehs7bA7OWQSQ4"
        }
      }' \

https://api.stormpath.com/v1/directories

Example Response

HTTP/1.1 201 Created
Location: https://api.stormpath.com/v1/directories/bckhcGMXQDujIXpbCDRb2Q
Content-Type: application/json;charset=UTF-8;

{
    "href": "https://api.stormpath.com/v1/directories/bckhcGMXQDujIXpbCDRb2Q",
    "name": "my-facebook-directory",
    "description": "A Facebook directory",
    "status": "ENABLED",
    "tenant": {
        "href": "https://api.stormpath.com/v1/tenants/60bD37asZX6JoFhyKFHiOk"
    },
    "provider": {
        "href": "https://api.stormpath.com/v1/directories/bckhcGMXQDujIXpbCDRb2Q/provider"
    },
    "accounts": {
        "href": "https://api.stormpath.com/v1/directories/bckhcGMXQDujIXpbCDRb2Q/accounts"
    },
    "groups": {
        "href": "https://api.stormpath.com/v1/directories/bckhcGMXQDujIXpbCDRb2Q/groups"
    }
}

After the Facebook Directory has been created, it needs to be mapped with an application as an account store. The Facebook Directory cannot be a default account store or a default group store. Once the directory is mapped to an account store for an application, you are ready to access Accounts with Facebook User Access Tokens.

Accessing Accounts with Facebook User Access Tokens

To access or create an account in an already created Facebook Directory, it is required to gather the User Access Token on behalf of the user. This usually requires leveraging Facebook’s javascript library and the user’s consent for your application’s permissions.

It is required that your Facebook application request for the email permission from Facebook. If the access token does not grant email permissions, you will not be able to get an Account with an access token.

Once the User Access Token is gathered, you can get or create the Account HTTP POSTing to the Application accounts collection and specifying the providerData JSON object. The providerData JSON object specifies the type of provider and the authorization code as follows:

{
  "providerId": "facebook",
  "accessToken": "%ACCESS_TOKEN_FROM_FACEBOOK%"
}

The following is how you use providerData to get an Account for a given User Access Token:

Example Request

curl -X POST --user $YOUR_API_KEY_ID:$YOUR_API_KEY_SECRET \
     -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -d '{
            "providerData": {
              "providerId": "facebook",
              "accessToken": "CABTmZxAZBxBADbr1l7ZCwHpjivBt9T0GZBqjQdTmgyO0OkUq37HYaBi4F23f49f5"
            }
          }' \
 "https://api.stormpath.com/v1/applications/24mp4us71ntza6lBwlu/accounts"

Example Response

HTTP/1.1 201 Created
Location: https://api.stormpath.com/v1/accounts/m0fw8GvxpM7n3pw6tyw9
Content-Type: application/json;charset=UTF-8;

{
    "customData": {
        "href": "https://api.stormpath.com/v1/accounts/m0fw8GvxpM7n3pw6tyw9/customData"
    },
    "directory": {
        "href": "https://api.stormpath.com/v1/directories/U0HJ7YcCeMpRfMcRT8ph"
    },
    "email": "[email protected]",
    "emailVerificationToken": null,
    "fullName": "Test User",
    "givenName": "Test",
    "groupMemberships": {
        "href": "https://api.stormpath.com/v1/accounts/m0fw8GvxpM7n3pw6tyw9/groupMemberships"
    },
    "groups": {
        "href": "https://api.stormpath.com/v1/accounts/m0fw8GvxpM7n3pw6tyw9/groups"
    },
    "href": "https://api.stormpath.com/v1/accounts/m0fw8GvxpM7n3pw6tyw9",
    "middleName": null,
    "providerData": {
        "href": "https://api.stormpath.com/v1/accounts/m0fw8GvxpM7n3pw6tyw9/providerData"
    },
    "status": "ENABLED",
    "surname": "User",
    "tenant": {
        "href": "https://api.stormpath.com/v1/tenants/GPpLzIzYkOO68I9i4dx"
    },
    "username": "testuser"
}

The HTTP Status code when accessing an account based on a Facebook User Access Token will denote if the account was created (201) or if it already existed in Stormpath (200)

To expand the providerData to get the Access Token for the Account in one HTTP request, add expand=providerData to the URL query parameters.

Once an Account is retreived, Stormpath maps common fields for the Facebook User to the Account. The access token for any additional calls in the providerData resource and can be retreived by:

GET https://api.stormpath.com/v1/accounts/m0fw8GvxpM7n3pw6tyw9/providerData

The returned providerData will include:

{
  "accessToken": "y29.1.AADN_Xo2hxQflWwsgCSK-WjSw1mNfZiv4", 
  "createdAt": "2014-04-01T17:00:09.154Z", 
  "href": "https://api.stormpath.com/v1/accounts/ciYmtETytH0tbHRBas1D5/providerData", 
  "modifiedAt": "2014-04-01T17:00:09.189Z", 
  "providerId": "facebook"
}

Administering Stormpath

For more information about administering Stormpath using the Admin Console, please refer to the Admin Console Product Guide.


Glossary of Terms

Attribute Description
Account An account is a unique identity within a directory. Stormpath does not use the term user because it implies a person, while accounts can represent a person, 3rd-party software, or non-human clients. Accounts can be used to log in to applications.
Agent An agent populates LDAP directories. An agent status reflects communication/error state because the agent is communicating with Stormpath.
API Key An API key is a unique ID paired with a secret value. API keys are used by software applications to communicate with Stormpath through the Stormpath REST API.
Application An application is a software application that communicates with Stormpath. It is typically a real world application that you are building, such as a web application, but it can also be infrastructural software, such as a Unix or Web server.
Authentication Authentication is the act of proving someone (or something) is actually who they say they are. When an account is authenticated, there is a high degree of certainty that the account identity is legitimate.
Authorization Authorization, also known as Access Control, is the process of managing and enforcing access to protected resources, functionality, or behavior.
Directory A directory is a collection of accounts and groups. Administrators can use different directories to create silos of accounts. For example, customers and employees can be stored in different directories.
Directory Agent A directory agent is a Stormpath software application installed on your corporate network to securely synchronize an on-premise directory, such as LDAP or Active Directory, into a Stormpath cloud directory.
Directory Mirroring Directory mirroring securely replicates selected data from one (source) directory to another (target or mirrored) directory for authentication and access control. The source directory is the authoritative source for all data. Changes are propagated to the target/mirror directory for convenience and performance benefits.
Group A group is a collection of accounts within a directory. In Stormpath, for anyone familiar with Role-Based Access Control, the term group is used instead of role.
Group Membership A group membership is a two-way mapping between an account and a group.
Account Store A account store is a directory or group associated with an application for account authentication. Accounts within account stores associated with an application can login to that application.
Account Store Mapping An account store mapping is a mapping between a group or directory and an application.
Identity Management Identity management is the management, authentication, authorization, and permissions of identities to increase security and productivity, while decreasing cost, downtime, and repetitive tasks.
Role A role is a classification of accounts, such as administrators or employees. In Stormpath, roles are represented as groups.
Role-Based Access Control Role-Based Access Control (RBAC) is the act of controlling access to protected resources or behavior based on the groups assigned to a particular account. RBAC is done using Stormpath groups.
REST API REST API is a software architectural style enabling data transfer and functionality using common web-based communication protocols. Stormpath provides a REST API for tenants so they can easily integrate Stormpath with their software applications.
Tenant A tenant is a private partition within Stormpath containing all data and settings—specifically your applications, directories, groups and accounts. When you sign up for Stormpath, a tenant is created for you. You can add other user accounts (for example, for your co-workers) to your tenant to help you manage your data. For convenience, many companies like to have one tenant where they can easily manage all application, directory, and account information across their organization.*

*You must know your tenant when logging in to the Admin Console website. There is a “Forgot Tenant” link on the login page if you do not know what your tenant is.


Help Us Spread the Word

Did you find this valuable? If you've enjoyed playing with Stormpath or are excited about what we've built, please help us spread the world with a quick tweet or by just telling a friend. Thank you!

Copyright © 2014 StormPath  |  All rights reserved