REST API Reference

Stormpath provides developers a simple, yet powerful REST+JSON API enabling user management control for organizations and applications.

The following items are covered in this document:

General Concepts
- Base URL
- Authentication
  - Basic Authentication Over HTTPS
  - Digest Authentication Over HTTPS
- Resource Format
- Resource Interaction, including:
- Collection Resources
- Resource References (Links)
  - Reference Expansion
- Errors
- HTTP Method Overloading
Resources

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:

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

HTTP Basic Authentication
Digest Authentication

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 login sources, wisely.

HTTPS

To help ensure data security, only secure (HTTPS) communication is allowed when communicating with the Stormpath API servers. Standard HTTP is not supported.

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 --user YOUR_API_KEY_ID:YOUR_API_KEY_SECRET --header "Accept: application/json" 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, Python and PHP) 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 langauge 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:

Java: Sauthc1Signer (the sign method)
Ruby: Sauthc1Signer (the sign_request method)
PHP: Sauthc1Signer (the signRequest method)
Python: Sauthc1Signer (the sign_request method)

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.

Note: The Stormpath SAuthc1 digest algorithm is NOT the same as HTTP digest authentication. The Stormpath SAuthc1 digest-based authentication scheme is much 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!

Retrieving Resources with HTTP GET

Request

You can retrieve a resource representation by GETting its url. The easiest way to do this is to copy and paste a URL into your web browser address bar.

An example API GET:

GET /v1/tenants/cJoiwcorTTmkDDBsf02AbA HTTP/1.1

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.
`415 UNSUPPORTED MEDIA TYPE`	The requested media type in the `Accept` header is unsupported. Stormpath's REST API currently only supports `application/json`.
`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"
}

Creating Resources with HTTP POST

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:

POST /v1/tenants/cJoiwcorTTmkDDBsf02AbA/applications HTTP/1.1
Content-Type: application/json

{
  "name": "Desired name",
  "description": "Desired description",
  "status": "enabled"
}

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`	The specified media type is not supported. Stormpath's REST API currently only supports `application/json`.
`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": "Best application ever",
  "description": "Really. The best application ever.",
  "status": "enabled",
  "tenant": {
    "href": "https://api.stormpath.com/v1/tenants/cJoiwcorTTmkDDBsf02AbA"
  },
  "loginSources": {
    "href": "https://api.stormpath.com/v1/applications/WpM9nyZ2TbaEzfbRvLk9KA/loginSources"
  },
  "accounts": {
    "href": "https://api.stormpath.com/v1/applications/WpM9nyZ2TbaEzfbRvLk9KA/accounts"
  }
}

Updating Resources with HTTP POST

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 properties of a resource, but at least one property 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 property:

POST /v1/applications/WpM9nyZ2TbaEzfbRvLk9KA HTTP/1.1
Content-Type: application/json

{
  "name": "New name"
}

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 property values. At at least one resource property 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 created 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`	The specified media type is not supported. Stormpath's REST API currently only supports `application/json`.
`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"
  },
  "loginSources": {
    "href": "https://api.stormpath.com/v1/applications/WpM9nyZ2TbaEzfbRvLk9KA/loginSources"
  },
  "accounts": {
    "href": "https://api.stormpath.com/v1/applications/WpM9nyZ2TbaEzfbRvLk9KA/accounts"
  }
}

Deleting Resources with HTTP DELETE

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

Request

An example DELETE request:

DELETE /v1/applications/WpM9nyZ2TbaEzfbRvLk9KA HTTP/1.1

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

Collection Resources

A Collection Resource is a resource containing other resources. It is known as a Collection Resource because it is 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 instance resources, you must interact 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:

GET /v1/tenants/cJoiwcorTTmkDEXAMPLE/applications?offset=10&limit=40 HTTP/1.1

This example requests the application Collection Resource of the tenant 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 name/value pairs ...
    },
    ...,
    {
      ... Application 50 name/value pairs ...
    }
  ]
}

Sort Order

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 as follows:

/v1/accounts?orderBy=orderStatement1%2CorderStatement2%2C...%2CorderStatementN

When URL-decoded, it looks as follows:

/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-reference) attributes, such as integers and strings.
optionalAscendingOrDescendingStatementis 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 (last name), asc first and then givenName (first name) desc:

/v1/applications/someRandomId/accounts?orderBy=surname%2CgivenName%20desc

Which, if URL decoded, is as follows:

/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 resources by interacting with a Collection Resource. You can search for specific items in the collection using 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 reference (link) expansion.

Note: 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, as follows:

/v1/someCollection?q=some+criteria

For example, a simple search across the accounts of an application (an account collection resource) for any searchable field containing 'Joe' is written as follows:

/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 tenant, are returned in the query results.

For example, consider the following query:

/v1/accounts?q=Joe

This returns all accounts where:

Each account is owned by the caller 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
Other account variables equal or contain 'joe' (case insensitive)

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 as follows:

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, as follows:

/v1/someCollection?anAttribute=someValue&anotherAttribute=anotherValue

For example, a search for the accounts of an application with a givenName of Joe is written as follows:

/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 an 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:

/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).

Note: 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.

Resource References or Links

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

A Resource Reference 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 referenced resource.

Example Resource Reference in JSON:

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

The following example the account resource has four resource references - groups, groupMemberships, directory, and tenant:

{
  "href": "https://api.stormpath.com/v1/accounts/ZugcG3JHQFOTKGEXAMPLE",
  "username": "lonestarr",
  "email": "lonestarr@druidia.com",
  "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 resource reference object, you can use the reference href attribute to interact with that resource as necessary.

Reference (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 the referenced resources. Reference expansion allows you to retrieve related information in a single request to the server instead of having to issue multiple separate requests.

`expand` Query Parameter

Using the previous example account resource, to retrieve the account including the parent directory information, instead of issuing two requests (one for the account and another for the directory) add an expand query parameter to the resource URI when requesting the account with a value of directory.

For example:

GET /v1/accounts/ZugcG3JHQFOTKGEXAMPLE?expand=directory

Response:

{
    "href": "https://api.stormpath.com/v1/accounts/ZugcG3JHQFOTKGEXAMPLE",
    "username": "lonestarr",
    "email": "lonestarr@druidia.com",
    "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"
    },
}

The account directory attribute is no longer a reference and has been expanded in-line and included in the response body. You can use this technique effectively when customizing user interfaces or reducing the number of round-trip communication requests to Stormpath API server, enhancing the performance of your application.

Expandable Attributes

Most reference attributes are expandable. Check the specific documentation for the resource to see which reference attributes are expandable.

Expansion Depth Limit

It is currently only possible to expand the immediate references of a resource. It is not currently possible to expand references of references.
For example, in the same example account it would not be possible to return the account with the directory and directory groups expanded. Expansion is currently only possible down one level.

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

Expanding Multiple References

You can specify more than reference attribute by specifying a comma-delimited list of attribute names to expand.
For example, to expand the example account directory and tenant references, pass the following GET request:

GET /v1/accounts/ZugcG3JHQFOTKGEXAMPLE?expand=directory,tenant

Expanding Collection References

If the reference you want to expand is a Collection Resource, you can expand it. You can also provide pagination parameters to control the paged output of the expanded collection.
For example, to expand the example account 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:

GET /v1/accounts/ZugcG3JHQFOTKGEXAMPLE?expand=groups(offset:0,limit:10)

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

Note: 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.

For more information on pagination, please see Collection Resource Pagination

Expansion Combinations

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

GET /v1/accounts/ZugcG3JHQFOTKGEXAMPLE?expand=directory,groups(offset:0,limit:10)

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

Errors

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

Property	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:

GET /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://www.stormpath.com/docs/errors/404"
}

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; method is prefixed with the underscore character. 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:

DELETE /v1/applications/WpM9nyZ2TbaEzfbRvLk9KA

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

POST /v1/applications/WpM9nyZ2TbaEzfbRvLk9KA?_method=DELETE

Resources

Applications

An application in Stormpath represents a real world application that can communicate with and be provisioned by Stormpath. After it is defined, an application is mapped to one or more directories or groups, whose users are then granted access to the application.

You can control access to your Stormpath Admin Console and API by managing the login sources for the listed Stormpath application.

Application Instance Resource

An application instance resource represents a software application that is registered to and communicates with Stormpath for application-specific user management needs. A tenant can register one or more applications with Stormpath.

Resource URI

/v1/applications/:applicationId

Resource Properties

Property	Description	Type	Valid Value
`href`	The resource fully qualified location URI	String	--
`name`	Name of the application. Must be unique within a tenant and across all tenant applications.	String	1 < N <= 255 characters
`description`	The description of the application.	String	0 < N <= 1000 characters
`status`	Enabled applications accept logins from accounts in assigned loginSources. Disabled applications deny logins.	Enum	`enabled`,`disabled`
`accounts`	A link to the accounts that can log in to the application. This list is an aggregate view of all accounts in the application assigned login sources.	Link	--
`tenant`	A link to the owning tenant.	Link	--
`passwordResetTokens`	A link to the password reset token endpoint so password reset tokens can be created and specific tokens can be viewed.	Link	--

Supported Operations

The following operations are supported on an existing individual application instance resource:

Read (HTTP GET)
Update (HTTP POST)
Delete (HTTP DELETE)
Create (HTTP POST)
List Accounts (HTTP GET)

New applications can be registered with Stormpath by creating an application instance resource using the application Collection Resource URI.

Read an Application Resource (HTTP GET)

Returns a representation of an application resource that includes the resource properties.

Example Request

GET /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",
  "accounts": {
    "href": "https://api.stormpath.com/v1/applications/WpM9nyZ2TbaEzfbRvLk9KA/accounts"
  },
  "tenant": {
    "href": "https://api.stormpath.com/v1/tenants/cJoiwcorTTmkDDBsf02AbA"
  },
  "passwordResetTokens" : {
      "href" : "http://localhost:8080/v1/applications/WpM9nyZ2TbaEzfbRvLk9KA/passwordResetTokens"
    },
}

Update an Application Resource (HTTP POST)

Use HTTP POST when you want to change one or more specific properties of an application resource. Unspecified properties are not changed, but at least one property must be specified.

Optional Properties

name
description
status

Example Request

POST /v1/applications/WpM9nyZ2TbaEzfbRvLk9KA
Content-Type: application/json

{
  "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",
  "accounts": {
    "href": "https://api.stormpath.com/v1/applications/WpM9nyZ2TbaEzfbRvLk9KA/accounts"
  },
  "tenant": {
    "href": "https://api.stormpath.com/v1/tenants/cJoiwcorTTmkDDBsf02AbA"
  },
  "passwordResetTokens" : {
  "href" : "http://localhost:8080/v1/applications/WpM9nyZ2TbaEzfbRvLk9KA/passwordResetTokens"
    },
}

Delete or Unregister an Application Resource (HTTP DELETE)

Permanently deletes a specific application resource.

Example Request

DELETE /v1/applications/WpM9nyZ2TbaEzfbRvLk9KA

Example Response

HTTP/1.1 204 No Content

Create or Register an Application Resource (HTTP POST)

Creates a new application instance within the caller tenant.

Resource URI

/v1/applications

Required Properties

name

Optional Properties

description
status - if unspecified, the default is enabled.

Example Request

POST /v1/applications
Content-Type: application/json

{
  "name": "Best application ever",
  "description": "A new description.",
  "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": "A new description.",
  "status": "enabled",
  "accounts": {
    "href": "https://api.stormpath.com/v1/applications/WpM9nyZ2TbaEzfbRvLk9KA/accounts"
  },
  "tenant": {
    "href": "https://api.stormpath.com/v1/tenants/cJoiwcorTTmkDDBsf02AbA"
  },
  "passwordResetTokens" : {
  "href" : "http://localhost:8080/v1/applications/WpM9nyZ2TbaEzfbRvLk9KA/passwordResetTokens"
    },
}

Child Collection Resources

The following collections are supported on an existing individual application instance resource:

Accounts Collection
Login Attempts
Password Reset Tokens

For more information about working with collections, click here.

Account Collections for an Application Resource

The Application Accounts Collection Resource represents all accounts that can log in to the application.

Resource URI

/v1/applications/:applicationId/accounts

List Application Accounts (HTTP GET)

HTTP GET returns a paginated list of links for accounts within a specified application.

Example Request

GET /v1/applications/WpM9nyZ2TbaEzfbRvLk9KA/accounts

Example Response

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

{
  "href": "https://api.stormpath.com/v1/applications/WpM9nyZ2TbaEzfbRvLk9KA/accounts"
  "offset": 0,
  "limit": 25,
  "items": [
    { 
      "href" : "https://api.stormpath.com/v1/accounts/cJoiwcorTTmkDDBsf02bAb"
    },
    {
      "href" : "https://api.stormpath.com/v1/accounts/tHEcAkeiSAlIe9sdh8KjdJda"
    }, 
    {
      "href" : "https://api.stormpath.com/v1/accounts/Gu8oshf7HdsspjHs3uhd7jGd"
    }
  ]
}

Login Attempts for Authenticating an Application Account

The Application Login Attempts endpoint allows an application to authenticate its associated accounts.

Resource URI

/v1/applications/:applicationId/loginAttempts

Login Attempt Resource Properties

Property	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` and plaintext password `mySecretPassword` this `value` property 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

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 Properties.

Example Request

POST /v1/applications/WpM9nyZ2TbaEzfbRvLk9KA/loginAttempts
Content-Type: application/json

{
  "type": "basic",
  "value": "QWxhZGRpbjpvcGVuIHNlc2FtZQ=="
}

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/cJoiwcorTTmkDDBsf02bAb"
  }
}

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:support@stormpath.com"
}

Password Reset Tokens for Reseting an Application Account Password

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

Creating a new password reset token automatically sends a password reset email to the destination email address if that address corresponds to an account listed in the application login sources.

With the application password reset tokens, you can:

Set Application Password Reset Token Resource Properties
Create Account Password Reset Token (Initiate password reset workflow) (HTTP POST)
Read a Password Reset Token (Validate password reset token) (HTTP GET)

Resource URI

/v1/applications/:applicationId/passwordResetTokens

Set Application Password Reset Token Resource Properties

Property	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.

Create Account Password Reset Token (Initiate password reset workflow) (HTTP POST)

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 property:

Example Request

POST /v1/applications/WpM9nyZ2TbaEzfbRvLk9KA/passwordResetTokens
Content-Type: application/json

{
  "email": "john.smith@stormpath.com"
}

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" : "john.smith@stormpath.com",
  "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 400 Bad Request
Content-Type: application/json;charset=UTF-8

{
  "status": 400,
  "code": 400,
  "message": "There is no account with that email address.",
  "developerMessage": "There is no account with the specified email address currently accessible to the specified application.",
  "moreInfo": "mailto:support@stormpath.com"
}

Read a Password Reset Token (Validate password reset token) (HTTP GET)

Reading a token resource successfully indicates the token is valid. If you obtain the token because the email recipient clicks a link to your application and it verifies successfully, you can assume the token is valid.

After verifying that the token is valid, you can then collect the new account password, using a web form over HTTPS, and submit the new password as an account update.

Example GET Request

GET /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": "john.smith@stormpath.com",
  "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 password validation link is not valid. You might want to try to reset your password again.",
   "developerMessage": "The specified password reset token does not exist. It may have expired. A new password reset token should be created to reset the account password.",
   "moreInfo": "mailto:support@stormpath.com"
 }

Receving a 404 Not Found response from a password reset token resource indicates the token is invalid and the end-user should not be asked to present a new password. A new password reset token should be constructed to initiate the password reset workflow.

Directories

A directory is a named root-level container of groups and accounts within a tenant.

Directories contain authentication and authorization information about users and groups. Stormpath supports an unlimited number of directories. Administrators can use different directories to create silos of users. For example, you might store your customers in one directory and your employees in another.

Within Stormpath, there are two types of directories you can implement:

A Cloud directory, also known as Stormpath-managed directories, which are hosted by Stormpath and use the Stormpath data model to store user and group information. This is the default and most common type of directory in Stormpath.
A mirroreddirectory, which is a Stormpath-hosted directory populated with data pushed from your existing LDAP/AD directory using a Stormpath synchronization agent. All user management is done on your existing LDAP/AD directory, but the cloud mirror can be accessed through the Stormpath APIs on your modern applications.
- Mirrored directories cannot be created using the API.
- You can specify various LDAP/AD object and attribute settings of the specific LDAP/AD server for users and groups.
- If the agent status is Online, but you are unable to see any data when browsing your LDAP/AD mapped directory, it is likely that your object and filters are configured incorrectly.

For more information about directories, see the Stormpath Admin Console Product Guide.

Directory Instance Resource

Resource URI

/v1/directories/:directoryId

Resource Properties

Property	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 login sources 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	--

Supported Operations

The following operations are supported on an existing individual directory instance resource:

Read (HTTP GET)
Update (HTTP POST)
Delete (HTTP DELETE)
Create (HTTP POST)
List Groups (HTTP GET)
List Accounts (HTTP GET)

Read a Directory Resource (HTTP GET)

HTTP GET returns a representation of a directory resource that includes the resource properties.

Example Request

GET /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"
  },
}

Update a Directory Resource (HTTP POST)

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

Optional Properties

name
description
status

Example Request

POST /v1/directories/bckhcGMXQDujIXpbCDRb2Q
Content-Type: application/json

{
  "name" : "Captains",
}

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",
  "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"
  }
}

Delete a Directory Resource (HTTP DELETE)

Permanently deletes a specific a directory resource.

Example Request

DELETE /v1/directories/bckhcGMXQDujIXpbCDRb2Q

Example Response

HTTP/1.1 204 No Content

Create a Directory Resource (HTTP POST)

Creates a new directory resource within the caller tenant.

Resource URI

/v1/directories

Required Properties

name

Optional Properties

description
status

Example Request

POST /v1/directories
Content-Type: application/json

{
  "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"
  },
}

Child Collection Resources

The following collections are supported on an existing individual directory instance resource:

Groups Collections for a Directory Resource
Accounts Collection for a Directory Resource

For more information about working with collections, click here.

Directory Groups Collection

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

Resource URI

/v1/directories/:directoryId/groups

List Directory Groups (HTTP GET)

HTTP GET returns a Collection Resource containing links for all groups owned by a specific directory.

Example Request

GET /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"
    },
    {
      "href" : "https://api.stormpath.com/v1/groups/sUcKIttrebEcKhgU86Kl0u"
    }, 
    {
      "href" : "https://api.stormpath.com/v1/groups/Yu8ihas7HOpjHs3uhd7jGd"
    },
  ]
}

Directory Accounts Collection

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

Resource URI

/v1/directories/:directoryId/accounts

List Directory Accounts Applications (HTTP GET)

HTTP GET returns a paginated list of links for accounts within a specified directory.

Example Request

GET /v1/directories/bckhcGMXQDujIXpbCDRb2Q/accounts

Example Response

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

{
  "href": "https://api.stormpath.com/v1/directories/bckhcGMXQDujIXpbCDRb2Q/accounts"
  "offset": 0,
  "limit": 25,
  "items": [
    { 
      "href" : "https://api.stormpath.com/v1/accounts/cJoiwcorTTmkDDBsf02bAb"
    },
    {
      "href" : "https://api.stormpath.com/v1/accounts/tHEcAkeiSAlIe9sdh8KjdJda"
    }, 
    {
      "href" : "https://api.stormpath.com/v1/accounts/Gu8oshf7HdsspjHs3uhd7jGd"
    }
  ]
}

Accounts

In Stormpath, users are referred to as user account objects or accounts. The username and email fields for accounts are unique within a directory and are used to log into applications. Within Stormpath, an unlimited number of accounts per directory is supported.

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.

Account Instance Resource

Resource URI

/v1/accounts/:accountId

Resource Properties

Property	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 property if setting or changing the account password.	String	1 < N <= 255 characters
`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.	Enum	`enabled`,`disabled`
`groups`	A link to the groups that the account belongs to.	Link	--
`directory`	A link to the owning directory.	Link	--
`tenant`	A link to the tenant owning the directory the group belongs to.	Link	--

Supported Operations

The following operations are supported on an existing individual account instance resource:

Read (HTTP GET)
Update (HTTP POST)
Delete (HTTP DELETE)
Create (HTTP POST)
List Groups (HTTP GET)

Read an Account Resource (HTTP GET)

HTTP GET returns a representation of an account resources that includes the properties.

Example Request

GET /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" : "capt@enterprise.com",
  "givenName" : "Jean-Luc",
  "middleName" : "",
  "surname" : "Picard",
  "status" : "enabled",
  "directory" : {
    "href" : "https://api.stormpath.com/v1/directories/WpM9nyZ2TbaEzfbRvLk9KA"
  },
  "groups" : {
    "href" : "https://api.stormpath.com/v1/accounts/cJoiwcorTTmkDDBsf02AbA/groups"
  }
    "groupMemberships" : {
  "href" : "https://api.stormpath.com/v1/accounts/BYb8_4SBRR2rmTv7FG47cQ/groupMemberships"
    },
"tenant" : {
  "href" : "https://api.stormpath.com/v1/tenants/tqjB6LiESGO00qvC4QDk8w"
},
}

Update an Account Resource (HTTP POST)

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

Optional Properties

username
email
password
givenName
middleName
surname
status

Example Request to Update the Name

POST /v1/accounts/cJoiwcorTTmkDDBsf02bAb
Content-Type: application/json

{
  "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" : "capt@enterprise.com",
  "givenName" : "Jean-Luc",
  "middleName" : "",
  "surname" : "Picard",
  "status" : "enabled",
  "directory" : {
    "href" : "https://api.stormpath.com/v1/directories/WpM9nyZ2TbaEzfbRvLk9KA"
  },
  "groups" : {
    "href" : "https://api.stormpath.com/v1/accounts/cJoiwcorTTmkDDBsf02AbA/groups"
  }
}

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

Example Request to Add an Account to a Group

POST https://api.stormpath.com/v1/groupMemberships
 Content-Type: application/json

 {
   "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"
   }
 }

Example Request to Change an Account Password

POST /v1/accounts/cJoiwcorTTmkDDBsf02bAb
Content-Type: application/json

{
  "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" : "capt@enterprise.com",
  "givenName" : "Jean-Luc",
  "middleName" : "",
  "surname" : "Picard",
  "status" : "enabled",
  "directory" : {
    "href" : "https://api.stormpath.com/v1/directories/WpM9nyZ2TbaEzfbRvLk9KA"
  },
  "groups" : {
    "href" : "https://api.stormpath.com/v1/accounts/cJoiwcorTTmkDDBsf02AbA/groups"
  }
}

Delete an Account Resource (HTTP DELETE)

Permanently deletes an account resource.

Example Request to Delete an Account

DELETE /v1/accounts/cJoiwcorTTmkDDBsf02bAb

Example Response

HTTP/1.1 204 No Content

Example Request to Remove an Account from a Group

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

Example Response

HTTP/1.1 204 No Content

Create an Account (HTTP POST)

Creates a new account resource instance within a specified directory.

Resource URI

/v1/directories/:directoryId/accounts

Required Properties

email
password
givenName
surname

Optional Properties

username
middleName
status

Example Request

POST /v1/directories/WpM9nyZ2TbaEzfbRvLk9KA/accounts
Content-Type: application/json

{
  "username" : "jlpicard",
  "email" : "capt@enterprise.com",
  "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" : "capt@enterprise.com",
  "givenName" : "Jean-Luc",
  "middleName" : "",
  "surname" : "Picard",
  "status" : "enabled",
  "directory" : {
    "href" : "https://api.stormpath.com/v1/directories/WpM9nyZ2TbaEzfbRvLk9KA"
  },
  "groups" : {
    "href" : "https://api.stormpath.com/v1/accounts/cJoiwcorTTmkDDBsf02AbA/groups"
  }
}

Child Collection Resources

Groups Collection for an Account Resource and Group Memberships Collection for an Account Resource are supported on an existing individual account instance resource.

For more information about working with collections, click here.

Groups Collection for an Account Resource

The Groups Collection for an Account Resource Collection Resource represents all groups where a specific account is a member.

Resource URI

/v1/accounts/:accountId/groups

List Account Groups (HTTP GET)

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

Example Request

GET /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"
    },
    {
      "href" : "https://api.stormpath.com/v1/groups/sUcKIttrebEcKhgU86Kl0u"
    }, 
    {
      "href" : "https://api.stormpath.com/v1/groups/Yu8ihas7HOpjHs3uhd7jGd"
    }
  ]
}

Group Memberships Collection for an Account Resource

The Group Memberships Collection for an Account Resource represents all group memberships where a specific account is a member.

Resource URI

/v1/accounts/:accountId/groupMemberships

List Account Group Memberships (HTTP GET)

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"
        }
  } ]
}

Groups

A group is a named collection of accounts within a directory. Groups can be used as login sources within applications to control who can login to an application.

Group Instance Resource

Resource URI

/v1/groups/:groupId

Resource Properties

Property	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`
`tenant`	The tenant that owns the directory containing this group.	Link	--
`directory`	A link to the directory resource that the group belongs to.	Link	--
`groups`	A link to the accounts that are contained within this group.	Link	--

Supported Operations

The following operations are supported on an existing individual group instance resource:

Read (HTTP GET)
Update (HTTP POST)
Delete (HTTP DELETE)
Create (HTTP POST)
List Accounts (HTTP GET)

Read a Group Resource (HTTP GET)

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

Example Request

GET /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"
  }
}

Update a Group Resource (HTTP POST)

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

Optional Properties

name
description
status

Example Request

POST /v1/groups/ZgoHUG0oSoVNeU0K4GZeVQ
Content-Type: application/json

{
  "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"
  }
}

Delete a Group Resource (HTTP DELETE)

Permanently deletes a specific a group resource.

Example Request

DELETE /v1/groups/ZgoHUG0oSoVNeU0K4GZeVQ

Example Response

HTTP/1.1 204 No Content

Create a Group Resource (HTTP POST)

Creates a new group resource instance in a specified directory.

Resource URI

/v1/directories/:directoryId/groups

Required Properties

name

Optional Properties

description
status

Example Request

POST /v1/directories/bckhcGMXQDujIXpbCDRb2Q/groups
Content-Type: application/json

{
  "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"
  }
}

Child Collection Resources

Group Account Collection for a Group Resource and Group Memberships Collection for a Group Resource are supported on an existing individual group instance resource.

For more information about working with collections, click here.

Group Accounts Collection

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

Resource URI

/v1/groups/:groupId/accounts

List Group Accounts (HTTP GET)

HTTP GET returns a paginated list of links for accounts within a specified group.

Example Request

GET /v1/groups/ZgoHUG0oSoVNeU0K4GZeVQ/accounts

Example Response

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

{
  "href": "https://api.stormpath.com/v1/groups/ZgoHUG0oSoVNeU0K4GZeVQ/accounts"
  "offset": 0,
  "limit": 25,
  "items" : [
    { 
      "href" : "https://api.stormpath.com/v1/accounts/cJoiwcorTTmkDDBsf02bAb"
    },
    {
      "href" : "https://api.stormpath.com/v1/accounts/tHEcAkeiSAlIe9sdh8KjdJda"
    }, 
    {
      "href" : "https://api.stormpath.com/v1/accounts/Gu8oshf7HdsspjHs3uhd7jGd"
    }
  ]
}

Group Memberships Collection for a Group Resource

The Group Memberships Collection for a Group Resource represents all group memberships where a specific group is a member.

Resource URI

/v1/groups/:groupId/accountMemberships

List Groups Group Memberships (HTTP GET)

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"
        }
  } ]
}

Group Memberships

A group membership is a named root-level container of the relationship between an account and a group within a tenant.

Group Membership Instance Resource

Resource URI

v1/groupMemberships/:groupMembershipId

Resource Properties

Property	Description	Type
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

Supported Operations

The following operations are supported on an existing individual group instance resource:

Read (HTTP GET)
Delete (HTTP DELETE)
Create (HTTP POST)

Read a Group Membership Resource

HTTP GET returns a representation of a group membership 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"
   }
}

Delete a Group Membership Resource

Permanently deletes a specific group membership resource.

Example Request

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

Example Response

HTTP/1.1 204 No Content

Create a Group Membership Resource

Creates a new group membership instance within a tenant.

Resource URI

v1/groupMemberships

Example Request

POST https://api.stormpath.com/v1/groupMemberships
    Content-Type: application/json

{
  "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"
   }
}

Tenants

Stormpath is a multitenant software service. When you sign up for the Stormpath service, a tenant instance is created for you. As a Stormpath customer, you own your tenant instance and everything you create in it - applications, directories, accounts, groups, and so on. You can access and update your tenant information using the Tenant REST API.

Tenant Instance Resource

Resource URI

/v1/tenants/:tenantId

Resource Properties

Property	Description	Type	Valid Value
`href`	The resource fully qualified location URI	String	--
`name`	The name of the tenant. Must be unique across all tenants.	String	1 < N <= 255 characters
`key`	Human readable tenant key. Unique across all tenants.	String	--
`applications`	A link to the tenant registered applications.	link	--
`directories`	A link to the tenant registered directories.	link	--

Supported Operations

The following operations are supported on an existing individual group instance resource:

Read (HTTP GET)
Read Current (HTTP GET)
Update (HTTP POST)
List Directories (HTTP GET)
List Applications (HTTP GET)

Create and delete are currently not supported.

Read a Tenant Resource (HTTP GET)

Returns a representation of a tenant resource that includes the resource properties.

Example Request

GET /v1/tenants/cJoiwcorTTmkDDBsf02AbA

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"
  }
}

Read the Current Tenant Resource (HTTP GET)

Returns a 302 Found redirect to the tenant instance resource corresponding to the currently executing API caller. In other words, this endpoint redirects the API caller to the REST resource URI for the tenant.

Example Request

GET /v1/tenants/current

Example Response

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

Update a Tenant Resource (HTTP POST)

Use HTTP POST when you want to change one or more specific properties of a tenant resource. Unspecified properties are not changed. At least one property must be specified.

Optional Properties

name

Example Request

POST /v1/tenants/WpM9nyZ2TbaEzfbRvLk9KA

{
  "name": "New Name"
}

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "href" : "https://api.stormpath.com/v1/tenants/cJoiwcorTTmkDDBsf02AbA",
  "name" : "New Name",
  "applications": {
    "href": "https://api.stormpath.com/v1/tenants/cJoiwcorTTmkDDBsf02AbA/applications"
  },
  "directories": {
    "href": "https://api.stormpath.com/v1/tenants/cJoiwcorTTmkDDBsf02AbA/directories"
  }
}

Child Collection Resources

The following collections are supported on an existing individual tenant instance resource:

Directories Collection for a Tenant Resource
Applications Collection for a Tenant Resource

For more information about working with collections, click here.

Directories Collection for a Tenant Resource

The Directories Collection for a Tenant Resource Collection Resource represents all directories owned by a specific Tenant.

Resource URI

/v1/tenants/:tenantId/directories

List Tenant Directories (HTTP GET)

HTTP GET returns a Collection Resource containing links for all directories owned by a specific tenant.

Example request

GET /v1/tenants/Gh9238fksJlsieJkPkQuW/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"
    },  
    {
      "href" : "https://api.stormpath.com/v1/directories/lIKeabOss8w9fJf0fJfb34"
    }, 
    {
      "href" : "https://api.stormpath.com/v1/directories/Hfjks7kj9sfKfh9fhsPifa"
    }
  ]
}

Applications Collection for a Tenant Resource

The Applications Collection for a Tenant Resource Collection Resource represents all applications owned by a specific tenant.

Resource URI

/v1/tenants/:tenantId/applications

List Tenant Applications (HTTP GET)

HTTP GET returns a Collection Resource containing links for all applications owned by a specific tenant.

Example Request

GET /v1/tenants/cJoiwcorTTmkDDBsf02AbA/applications

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "href": "https://api.stormpath.com/v1/tenants/cJoiwcorTTmkDDBsf02AbA/applications",
  "offset": 0,
  "limit": 10,
  "items": [
    { 
      "href" : "https://api.stormpath.com/v1/applications/WpM9nyZ2TbaEzfbRvLk9KA"
    },
    {
      "href" : "https://api.stormpath.com/v1/applications/aLlyOUrBAse34js9hjiH9j"
    }, 
    {
      "href" : "https://api.stormpath.com/v1/applications/Xhf0a9HLA02djsdP90dsQ2"
    }
  ]
}

REST API Reference

General Concepts

Base URL

Authentication

Basic Authentication over HTTPS

Digest Authentication Over HTTPS

Resource Format

Retrieving Resources with HTTP GET

Creating Resources with HTTP POST

Updating Resources with HTTP POST

Deleting Resources with HTTP DELETE

Collection Resources

Pagination

Query Parameters

Sort Order

Search

Filter Search

Attribute Search

Resource References or Links

Reference (Link) Expansion

expand Query Parameter

Expandable Attributes

Expansion Depth Limit

Expanding Multiple References

Expanding Collection References

Expansion Combinations

Errors

HTTP Method Overloading

Resources

Applications

Application Instance Resource

Resource Properties

Supported Operations

Read an Application Resource (HTTP GET)

Update an Application Resource (HTTP POST)

Delete or Unregister an Application Resource (HTTP DELETE)

Create or Register an Application Resource (HTTP POST)

Child Collection Resources

Account Collections for an Application Resource

Login Attempts for Authenticating an Application Account

Password Reset Tokens for Reseting an Application Account Password

Directories

Directory Instance Resource

Resource Properties

Supported Operations

Read a Directory Resource (HTTP GET)

Update a Directory Resource (HTTP POST)

Delete a Directory Resource (HTTP DELETE)

Create a Directory Resource (HTTP POST)

Child Collection Resources

Directory Groups Collection

Directory Accounts Collection

Accounts

Account Instance Resource

Resource Properties

Supported Operations

Read an Account Resource (HTTP GET)

Update an Account Resource (HTTP POST)

Delete an Account Resource (HTTP DELETE)

Create an Account (HTTP POST)

Child Collection Resources

Groups Collection for an Account Resource

Group Memberships Collection for an Account Resource

Groups

Group Instance Resource

Resource Properties

Supported Operations

Read a Group Resource (HTTP GET)

Update a Group Resource (HTTP POST)

Delete a Group Resource (HTTP DELETE)

Create a Group Resource (HTTP POST)

Child Collection Resources

Group Accounts Collection

Group Memberships Collection for a Group Resource

Group Memberships

Group Membership Instance Resource

Resource Properties

Supported Operations

Read a Group Membership Resource

Delete a Group Membership Resource

`expand` Query Parameter