Before you can use Stormpath, you must first sign up for the service.  Sign-up and Developer-tier usage is 100% free, and no credit card is required.

To Sign Up

1. In the upper right corner of this page, enter your email address and then click the orange "Sign Up Now" button.  This will send you a confirmation email.
   
   
2. Click the link in the confirmation email.
   
   
3. Follow the onscreen instructions.
   
   

After completing this process, you are ready to use Stormpath for free!

If you need to make REST API requests to Stormpath, those requests must be authenticated with an API Key.

API keys are personally assigned to you and only you and should never be shared with anyone else, not even co-workers (co-workers should have their own API Keys if they need to communicate with Stormpath).

Here's how you get an API Key:

1. Login to the Stormpath Web UI Console, using the email address and password you used during sign-up.
   
   
2. After logging in, visit your account page by clicking on your name in the upper right-hand corner of the screen:
   
   
   
   
3. On the resulting Account Details page, click the 'Create API Key' button about halfway down:
   
   
   
   This will generate your API Key and download it to your computer as an apiKey.properties file. If you open the file in a text editor, you will see something similar to the following:
   

   apiKey.id = 144JVZINOF5EBNCMG9EXAMPLE
   apiKey.secret = lWxOiKqKPNwJmSldbiSkEbkNjgh2uRSNAb+AEXAMPLE
   

4. Save this file in a very private place! In your home directory in a hidden .stormpath directory is a good choice. For example, in 
   
   $HOME/.stormpath/apiKey.properties
   
   
5. Also change the file's permissions to ensure this file is readable by you and only you.  For example (on *nix operating systems):
   
   $ chmod go-rwx $HOME/.stormpath/apiKey.properties

This quickstart guide will help you connect to Stormpath's REST API quickly.

1. If you haven't already, Sign Up for Stormpath for free.
   
   
2. Ensure you have your own API Key.
   
   
3. Test that the key works by opening a client (like a web browser window) and using the following URL:
   
   https://api.stormpath.com/v1/tenants/current/
   
   Use the API Key id as the username and the API Key secretas the password.

   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 

If you see a successful JSON response for your Tenant data, you've successfully made an API request!

You are now ready to make REST requests to access all of your data via our full REST API.

Connecting with Stormpath SDK

To test the connection via one of the Stormpath SDK's you will need to create a Client instance with your API key, and retrieve your current tenant.

The following examples assume the user already has the specific SDK installed.

Using Java SDK:
(The Java SDK documentation is here: https://github.com/stormpath/stormpath-sdk-java/wiki)

 
import com.stormpath.sdk.client.*; 
... 
String path = System.getProperty("user.home") + "/.stormpath/apiKey.properties"; 
//assuming that the apiKey.properties file with your Stormpath API key was saved in this location with read access
Client client = new ClientBuilder().setApiKeyFileLocation(path).build();
Tenant tenant = client.getCurrentTenant();

Using Ruby SDK:
(The Ruby SDK documentation is here: https://github.com/stormpath/stormpath-sdk-ruby/wiki)

 
require "stormpath-sdk"
include Stormpath::Client
...
api_key_file = '/home/myhomedir/.stormpath/apiKey.yml' 
#assuming that the apiKey.yml file with your Stormpath API key (in YAML format) was saved in this location with read access
client = ClientBuilder.new.set_api_key_file_location(api_key_file).build
tenant = client.current_tenant

Using PHP SDK:
(The PHP SDK documentation is here: https://github.com/stormpath/stormpath-sdk-php/wiki)

 
$path = '/home/myhomedir/.stormpath/apiKey.yml'; 
//assuming that the apiKey.yml file with your Stormpath API key (in YAML format) was saved in this location with read access
$builder = new Services_Stormpath_Client_ClientBuilder;
$client = $builder->setApiKeyFileLocation($path)->build(); 
$tenant = $client->getCurrentTenant();

Configuring a REST Client

If you are NOT using one of the official Stormpath SDKs, you will need to configure your rest client for authentication and also to accept JSON content.

Depending on your REST library or client, you accept JSON typically by setting the Accept header with a value of application/json:

Accept: application/json

This ensures that the Stormpath API Server will respond with JSON data.

Once your REST client can authenticate and accept JSON, you will be able to access all of your data via our full REST API.

This guide shows how to register an application with Stormpath.  Registering an application quickly enables Stormpath's full user management features and security workflows for that application.

This guide assumes that you have already signed up for Stormpath.

Register your Application with Stormpath

1. Login into the Stormpath web UI console.  If you do not have a Stormpath account, please sign up or ask your existing Stormpath administrator to give you access.
   
   
2. After logging in, Click on the top-level "Applications" button and then click "Register Application":
   
   
   
   
3. Complete the Register Application wizard:
   
   
1. Wizard step 1. Details: Enter your application's name and optional description:
   
   
   
   
2. Wizard step 2. Directories: Choose one or more directories with user accounts that will log in to your application.  You must choose at least one directory, and you can create directories later.  In this getting started guide, we'll just choose the 'Stormpath Administrators' directory for simplicity.  
   
   
   
   
3. Wizard step 3. Groups: If you do not want an entire directory to be able to log in, you can configure specific groups within directories instead.  We'll just choose 'all  users' (representing all users in a Directory) in this example.
   
   
   
   
4. Wizard step 4. Confirm: Confirm your settings and click 'Finish'.
   
   
   
   
5. Your application is now registered! You will see it listed in the resulting Applications listing page
   
   

Congratulations!  You have registered your first application in Stormpath.  

You will probably want to make sure users can log in to your application.  Feel free to try that next:

Authenticate an Account

This guide shows you how to use Stormpath to log in (authenticate) your application's user accounts.

To authenticate users in an application, it is assumed that you have already:

1. Signed-up for Stormpath.
2. Ensured you can connect to the Stormpath REST API with your API Key.
3. Registered your Application within Stormpath and know its REST URL.
4. Assigned one or more Login Sources to your Application.  Assigning login sources (entire directories or groups within a directory) to an application defines its user base.

Contents

• Authentication Overview
• Using cURL
• Using httpie
• Using Java
• Using Ruby
• Using PHP

Authentication Overview

When you use Stormpath's REST API (via cURL, httpie, or one of our wrapper SDKs) to authenticate your application's user accounts, the basic flow is as follows:

1. Collect your end-user's plaintext username (or email) and password.
2. Base64-encode the user-submitted data.
3. Post the Base64-encoded data over SSL to your application's loginAttempts REST URL.

loginAttempts REST URL

Your application's loginAttempts URL is the application's Stormpath REST URL with /loginAttempts added to the end.  For example, if your application's Stormpath REST URL is:

https://api.stormpath.com/v1/applications/dRvH4y0nT6uNl6gEXAMPLE

then your application's login attempts URL is the following:

https://api.stormpath.com/v1/applications/dRvH4y0nT6uNl6gEXAMPLE/loginAttempts

This loginAttempts URL will be referenced in the instructions below.

1. Collect the submitted username (or email) and password

When your user logs into your application, they submit their username (or email address) and password directly to you.  For example, they might visit https://www.myAwesomeApplication.com/login, fill out a username/password form, and hit 'submit'.

Collect the user's submitted username (or email address) and password.  These are the raw text values submitted by your application's end user.  You can collect them in any way you wish (web form, mobile interface, desktop application, etc).  

Web applications MUST collect usernames/emails and passwords over HTTPS to ensure security.  (e.g. https://myapplication.com/login).  DO NOT use http for collecting login information.

2. Base64 encode the user-submitted data

Concatenate the username, the colon character ':', and the raw text password into a String.  Get the String's UTF-8 bytes, and then Base64 encode the bytes.  For example:

byte[] bytes = getUTF8Bytes( usernameOrEmailString + ":" + rawPasswordString)
String encoded = base64Encode( bytes )

This encoded value will be used in the next step.

3. POST a Login Attempt

After constructing the encoded value above, send an HTTP POST it to the application's loginAttempts URL with the following JSON body (don't forget to set the Accept and Content-Type headers!):

POST /v1/applications/dRvH4y0nT6uNl6gEXAMPLE/loginAttempts
Accept: application/json
Content-Type: application/json
  
{
  "type": "basic",
  "value": "QWxhZGRpbjpvcGVuIHNlc2FtZQ=="
} 

• The type property indicates the type of authentication being performed.  This must equal basic. Additional authentication types will be supported in the near future.
• The value property holds the encoded value from Step 2. 

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
 
{
  "account": {
    "href" : "https://api.stormpath.com/v1/accounts/cJoiwcorTTmkDDBsf02bAb" 
  }
}

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

For more information, see the complete LoginAttempt REST API documentation.

Authenticate a User Account with cURL

1. Base64 encode the user's submitted username (or email), colon character ':', and password.  For example, on *nix:
   
   $ echo 'account_username:account_password' | openssl base64
   YWNjb3VudF91c2VybmFtZTphY2NvdW50X3Bhc3N3b3JkCg==
   
   
2. Use your API Key ID and Secret and the base64 value and POST to your application's loginAttempts URL:
   
   $ curl --user API_KEY_ID:API_KEY_SECRET \
          -H "Accept: application/json" \
          -H "Content-Type: application/json"
          -d '{"type": "basic", \
          "value":"YWNjb3VudF91c2VybmFtZTphY2NvdW50X3Bhc3N3b3JkCg=="}' \
          https://api.stormpath.com/v1/applications/APP_UID/loginAttempts

Authenticate a User Account with httpie

1. Base64 encode the user's submitted username (or email), colon character ':', and password.  For example, on *nix:
   
   $ echo 'account_username:account_password' | openssl base64
   YWNjb3VudF91c2VybmFtZTphY2NvdW50X3Bhc3N3b3JkCg==
   
   
2. Use your API Key ID and Secret and the base64 value and POST to your application's loginAttempts URL:
   
   $ http -a API_KEY_ID:API_KEY_SECRET POST \
     https://api.stormpath.com/v1/applications/APP_UID/loginAttempts \
       type=basic value=YWNjb3VudF91c2VybmFtZTphY2NvdW50X3Bhc3N3b3JkCg==

Authenticate a User Account with Java

This example assumes you are using the Stormpath Java SDK.

Use your application's REST URL as the href variable value:

import com.stormpath.sdk.client.*;
import com.stormpath.sdk.ds.*;
import com.stormpath.sdk.application.*;
import com.stormpath.sdk.account.*;
import com.stormpath.sdk.authc.*;
...

String userHome = System.getProperty("user.home");
String path = userHome + "/.stormpath/apiKey.properties";
Client client = new ClientBuilder().setApiKeyFileLocation(path).build();
DataStore dataStore = client.getDataStore();

String href = "https://api.stormpath.com/v1/applications/APP_UID_HERE";
Application application = dataStore.getResource(href, Application.class);

// when the account is authenticated, it produces an AuthenticationResult
String un = "usernameOrEmail"; //get from form
String pw = "password"; //get from form
AuthenticationRequest request = new UsernamePasswordRequest(un,pw);
AuthenticationResult result = application.authenticateAccount(request);

// from the result instance we get the authenticated Account
Account account = result.getAccount();

Authenticate a User Account with Ruby

This example assumes you are using the Stormpath Ruby SDK.

Use your application's REST URL as the href variable value:

require "stormpath-sdk"
include Stormpath::Client
include Stormpath::Resource
include Stormpath::Authentication
...

api_key_file = '/home/myhomedir/.stormpath/apiKey.yml'
client = ClientBuilder.new.set_api_key_file_location(api_key_file).build

href = 'https://api.stormpath.com/v1/applications/APP_UID_HERE'
application = client.data_store.get_resource href, Application

# when the account is authenticated, it produces an AuthenticationResult
request = UsernamePasswordRequest.new 'usernameOrEmail', 'password'
result = application.authenticate_account request

# from the result, we obtain the authenticated Account
account = result.get_account

Authenticate a User Account with PHP

This example assumes you are using the Stormpath PHP SDK.

Use your application's REST URL as the $href variable value:

$path = '/home/myhomedir/.stormpath/apiKey.yml';
$builder = new Services_Stormpath_Client_ClientBuilder;
$client = $builder->setApiKeyFileLocation($path)->build(); 

$href = 'https://api.stormpath.com/v1/applications/APP_UID_HERE';
$ds = $client->getDataStore();
$application = $ds->getResource($href, Services_Stormpath::APPLICATION);

// when the account is authenticated, it produces an AuthenticationResult
$un = 'usernameOrEmail';
$pw = 'rawPassword';
$req = new Services_Stormpath_Authc_UsernamePasswordRequest($un,$pw);
$authResult = $application->authenticateAccount($req);

// from the result, we obtain the authenticated Account
$account = $authResult->getAccount();

Contents

• Key Concepts and Definitions
• Architectural Overview
• About the Administration Console
• About the REST API 

Key Concepts and Definitions

Account - Sometimes called 'users', an Account is more specifically a unique identity within a Directory.  Stormpath does not call these Users because the word 'user' usually implies a person. Accounts however can also represent 3rd-party software or non-human clients.  But you can essentially think of an account as Stormapth's 'User' concept.  Accounts may be used login to Applications.

API Key - A unique ID paired with a very secret value. The ID + the secret together are an API Key. API Keys are used by software applications to communicate with Stormpath IAM via the Stormpath REST API.

Application - A software application that can communicate with Stormpath.  This is usually your real world application that you are building, such as a web application, but it can also be infrastructural software, like a unix machine or web server.

Authentication - the act of proving someone (or something) is actually who they say they are.  When you authenticate an account, you have a high degree of certainty that the account identity is legitimate.

Authorization - (aka Access Control): the process of managing and enforcing access to protected resources, functionality or behavior.

Directory - A collection of accounts and groups. Administrators can use different directories to create silos of accounts. For example, you might store your customers in one directory and your employees in another.

Directory Agent - A Stormpath software application that you install in your corporate network to securely synchronize an on-premise Directory like LDAP or Active Directory into a Stormpath Cloud Directory.

Directory Mirroring - Securely replicating selected data from one directory (called the source directory) into another directory (the 'target' or 'mirrored' directory) for the purposes of 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 collection of accounts within a directory.  In Stormpath this serves the same purpose of a 'Role' for those familiar with Role-Based Access Control.

IAM - Identity and Access Manager.  The name of the core Stormpath product, accessed via API or web console.

Identity Management - the management of individual identities, their authentication, authorization, and permissions to increase security and productivity and decrease cost, downtime, and repetitive tasks.

Login Source - A Directory or Group associated with an Application for the purpose of account authentication.  Accounts within Login Sources that are associated with an Application may login to that Application.

Role - A classification of accounts, like 'administrators' or 'employees'.  In Stormpath IAM, roles are represented as Groups.  There is no concrete role concept - the word 'Role' is effectively a synonym for 'Group' in Stormpath.

Role-Based Access Control (aka RBAC) - The act of controlling access to protected resources or behavior based the groups assigned to a particular account.  In Stormpath, the word 'Group' is used instead of 'role'.  You perform RBAC using Stormpath Groups. 

REST API - a software architectural style enabling data transfer and functionality via common web-based communication protocols. Stormpath provides a REST API for Tenants so they may easily integrate Stormpath with their own software applications.

Tenant - A private partition within Stormpath that contains all of your data and settings—namely 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. Many companies like to have one tenant where they can easily manage all of their applications, directories and accounts across their organization for convenience.

Architectural Overview

About the Administration Console

The Stormpath Administration Console allows authorized administrators to:

• Configure applications to access the Stormpath Identity and Access Manager

• Create and manage accounts and adjust their group and role membership

• Create and manage directories and manage their groups and roles

• Map directories to allow accounts to log into integrated applications

• Configure workflow automations 

To access the Stormpath Administration Console, visit https://api.stormpath.com/login

About the REST API

The Stormpath API offers authorized developers and administrators programmatic access to:

• Securely authenticate an account

• Create and manage accounts and adjust their group and role membership

• Create and manage directories

• Create and manage groups and roles

• Initiate and process workflow automations

For more detailed documentation on the Stormpath API, visit the API Reference Documentation.

Directories contain authentication and authorization information about users, groups and roles. 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.

A directory can be one of the following types:

• Cloud Directory
  Cloud Directories are hosted by Stormpath and use the Stormpath data model to store user, group and role information. This is the most common type of directory in Stormpath.

• Cloud LDAP Mirror 
  Stormpath provides a synchronization agent for your existing LDAP directory. All user management will be done on your existing LDAP directory but the cloud mirror can be accessed via the Stormpath APIs by your modern applications.

Once you have created a directory in Stormpath, you can map it to applications. Stormpath will then route an application's login requests to the directory. Modification of directory entities (users accounts, groups and roles) can be done via the Stormpath Administration Console or Stormpath REST API.

You can also map multiple directories to an application, providing the application with a single view of multiple directories in a specified order. 

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

When you first create your tenant in Stormpath IAM, an application 'Stormpath IAM' is added by default and listed on your Application Browser.  You can control access to your Stormpath Console and API by managing the Login Sources for the 'Stormpath IAM' application listed. 

To add more directories, see Adding an Application. 

In Stormpath IAM, users are referred to as user accounts objects or just accounts. Accounts are unique within a directory and are used to log into applications.  Stormpath support an unlimited number of accounts per directory.

Groups are collections of user accounts within a directory and are often used for authorization and access control in an application. In Stormpath, a group serves the same purpose of a role so the two terms are used interchangeably.

Every request to Stormpath's REST API must be authenticated with an API Key.  If you wish to make a REST request to Stormpath, we assume you have already:

1. Signed up for Stormpath
2. Downloaded your API Key.

Once you have an API Key, you can choose one of two ways to authenticate with Stormpath: either with HTTP Basic Authentication or Digest Authentication.

Security Notice

Any account that may access the Stormpath IAM application within the Stormpath web UI 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 the Stormpath IAM application (via 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) present 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 may not be feasible for some projects.

All of the Stormpath SDKs 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 of choice, we recommend that you 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 might wish to attempt to port the algorithm to that language.  You can try to replicate the algorithm and use Stormpath's existing code as examples to help:

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

If you port the algorithm to other language(s), please do let us know!  We're happy to help!  Email us at support -at- stormpath.com or say hi on IRC (irc.mibbit.net:6667 and join #stormpath) and we'll help as best as we can.

*Note: Stormpath's 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.