2. Quickstart

Now that you’ve decided that Stormpath is right for you, let’s get you set up and working with Stormpath. This quickstart will begin with signing you up for Stormpath, and will end with you authenticating a newly created user.

If you have already signed-up for Stormpath and downloaded an API Key, you can jump to:

2.1 Sign-up for Stormpath

  1. Go to https://api.stormpath.com/register and complete the form.
  2. You will receive a confirmation email with an activation link.
  3. Once you click the link, Stormpath will create a Stormpath account along with a Tenant. Your Tenant name will be a unique pair of two randomly-generated words separated by a hyphen (e.g. “iron-troop”).

Note

Note your Tenant name! You will need this in the future in order to log-in to your Stormpath Admin Console.

  1. On this screen, re-enter your password and click “Log In” to enter the Admin Console. From here you will be able to perform all of the administrative functions required for your Stormpath Account. You should start by creating an API key.

2.2 Create an API Key Pair

In order to use the Stormpath API, you will need an API key. To get one, follow these steps:

  1. On the right side of the Admin Console, under “Developer Tools”, click the “Create API Key” button.
  2. A dialog box will come up, with additional information about the key. You will now be able to download your key in the form of a apiKey-{API_KEY_ID}.properties file. This file contains your Stormpath API Key information, which can be used to authenticate with the Stormpath API.

Note

We recommend that you rename the file apiKey.properties to remove the Key ID, and then store it in a secure location. For example, you could place it in a hidden .stormpath directory in your private user profile directory.

On Mac and Linux, you could run these commands in bash or the Terminal:

$ mkdir ~/.stormpath
$ mv ~/Downloads/apiKey-{$API_KEY_ID}.properties ~/.stormpath/apiKey.properties
$ chmod go-rwx ~/.stormpath/apiKey.properties

On Windows, you could run these commands in the Command Prompt:

mkdir %homepath%\.stormpath
copy %homepath%\Downloads\apikey-{$API_KEY_ID}.properties %homepath%\.stormpath\apiKey.properties

Or in PowerShell:

mkdir $Home\.stormpath
cp $Home\Downloads\apiKey-{$API_KEY_ID}.properties $Home\.stormpath\apiKey.properties

2.3 Installing the SDK

This step is not relevant to the REST Product Guide, but would be required if you were using one of these SDKs:

These instructions assume that you have cURL installed on your system and that you have already completed the steps above, and now have:

  • A Stormpath account
  • A Stormpath API Key generated and downloaded onto your system
  • A Stormpath Tenant resource.

The following associated resources were also automatically created:

  • Two Application resources: One called “My Application”, and the other called “Stormpath”
  • Two Directory resources: “My Application Directory” and “Stormpath Administrators”
  • “My Application Directory” is set as the default Directory for any new Accounts added to “My Application”.
  • An Account resource representing your Stormpath Administrator user.
Default Stormpath Resources

These are the default resources that exist in your Tenant right after registration

In this section of the quickstart, you will:

Stormpath also can do a lot more (like Groups, Multitenancy, and Social Integration) which you can learn more about later in this guide.

Let’s get started!

2.4. Retrieve Your Application

Before you can create user Accounts, you’ll need to retrieve your Stormpath Application. An Application in Stormpath represents the project that you are working on. This means that, if you’re building a web app named “Lightsabers Galore”, you’d want to name your Stormpath Application “Lightsabers Galore” as well. By default, your Stormpath Tenant will have an Application already created for you to use. We will use this Application, named “My Application”, for the quickstart.

Before you can get your Application, you must get the location of your Tenant from Stormpath, like so:

curl --request GET \
  --verbose \
  --user $SP_API_KEY_ID:$SP_API_KEY_SECRET \
  --header 'content-type: application/json' \
  --url "https://api.stormpath.com/v1/tenants/current"
  • $SP_API_KEY_ID is the apiKey.id value in apiKey.properties and
  • $SP_API_KEY_SECRET is the apiKey.secret value in apiKey.properties

The above cURL command returns an empty body along with a header:

HTTP/1.1 302 Found
Location: https://api.stormpath.com/v1/tenants/$TENANT_ID
Content-Length: 0

Make note of the Location header. This is the location of your Tenant in Stormpath, with the Tenant’s unique ID at the end.

From here, using your Tenant ID, you can get your Application by performing a search for the Application by name, with $TENANT_ID replaced with your Tenant’s ID from the previous cURL:

curl --request GET \
  --user $SP_API_KEY_ID:$SP_API_KEY_SECRET \
  --header 'content-type: application/json' \
  --url "https://api.stormpath.com/v1/tenants/$TENANT_ID/applications?name=My%20Application"

Note

If you leave off the ?name=My%20Application' query at the end of the request, it will instead retrieve a list of all Applications for this Tenant.

The above cURL would return this example response:

{
  "href":"https://api.stormpath.com/v1/applications/1gk4Dxzi6o4PbdlEXampLE",
  "name":"My Application",
  "description":"This application was automatically created for you in Stormpath for use with our Quickstart guides(https://docs.stormpath.com). It does apply to your subscription's number of reserved applications and can be renamed or reused for your own purposes.",
  "status":"ENABLED",
  "createdAt":"2015-08-18T20:46:36.061Z",
  "modifiedAt":"2015-11-09T21:09:34.334Z",
  "tenant":{
    "href":"https://api.stormpath.com/v1/tenants/1gBTncWsp2ObQGgExAMPLE"
  },
  "comment":" // This JSON has been truncated for readability",
  "accounts":{
    "href":"https://api.stormpath.com/v1/applications/1gk4Dxzi6o4PbdlEXampLE/accounts"
  },
  "groups":{
    "href":"https://api.stormpath.com/v1/applications/1gk4Dxzi6o4PbdlEXampLE/groups"
  },
  "accountStoreMappings":{
    "href":"https://api.stormpath.com/v1/applications/1gk4Dxzi6o4PbdlEXampLE/accountStoreMappings"
  },
  "loginAttempts":{
    "href":"https://api.stormpath.com/v1/applications/1gk4Dxzi6o4PbdlEXampLE/loginAttempts"
  },
  "comment":" // This JSON has been truncated for readability"
}

Make note of the accounts, loginAttempts, and href URLs in the above response. We’re now going to use these to create a new user Account and then authenticate it.

2.5. Create a User Account

Now that we’ve created an Application, let’s create a user Account so someone can log in to (i.e. authenticate with) the Application.

curl --request POST \
  --user $SP_API_KEY_ID:$SP_API_KEY_SECRET \
  --header 'content-type: application/json' \
  --url "https://api.stormpath.com/v1/applications/1gk4Dxzi6o4PbdlEXampLE/accounts"
  --data '{
  "givenName": "Joe",
  "surname": "Stormtrooper",
  "username": "tk421",
  "email": "tk421@stormpath.com",
  "password":"Changeme1"
  }'

This would return this response:

{
  "href": "https://api.stormpath.com/v1/accounts/2wufAnDszC3PRi9exAMple",
  "username": "tk421",
  "email": "tk421@stormpath.com",
  "fullName": "Joe Stormtrooper",
  "givenName": "Joe",
  "middleName": null,
  "surname": "Stormtrooper",
  "status": "ENABLED",
  "customData": {
    "href":"https://api.stormpath.com/v1/accounts/2wufAnDszC3PRi9exAMple/customData"
  },
  "groups": {
    "href":"https://api.stormpath.com/v1/accounts/2wufAnDszC3PRi9exAMple/groups"
  },
  "groupMemberships": {
    "href":"https://api.stormpath.com/v1/accounts/2wufAnDszC3PRi9exAMple/groupMemberships"
  },
  "directory": {
    "href":"https://api.stormpath.com/v1/directories/1gkPqEScsMQSUFreXAMPLE"
  },
  "tenant": {
    "href":"https://api.stormpath.com/v1/tenants/1gBTncWsp2ObQGgExAMPLE"
  },
  "emailVerificationToken": null
}

You’ll notice here that this user Account has a Directory href returned as well, even though you haven’t created one. This is because when you created an Application, Stormpath automatically created a new Directory as well.

2.6. Authenticate a User Account

Now we have a user Account that can use your Application. But how do you authenticate an Account logging in to the Application?

You POST a “Login Attempt” to your Application’s /loginAttempts endpoint.

The login cURL command would look as follows:

curl --request POST \
  --user $SP_API_KEY_ID:$SP_API_KEY_SECRET \
  --header 'content-type: application/json' \
  --url "https://api.stormpath.com/v1/applications/1gk4Dxzi6o4PbdlEXampLE/loginAttempts"
  --data '{
  "type": "basic",
  "value": "dGs0MjE6Q2hhbmdlbWUx"
  }'

We are sending a Login Attempt resource, which has two attributes: type and value.

The type attribute must equal basic. The value attribute must equal the result of the following (pseudo code) logic:

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

For example, if you used the tk421 username and Changeme1 password from above when creating your first account, you might compute the value using OpenSSL this way:

echo -n "tk421:Changeme1" | openssl base64

This would produce the following Base64 result:

dGs0MjE6Q2hhbmdlbWUx

This is what we passed as the value attribute.

If the authentication attempt is successful (the username and password match and were Base64-encoded correctly), a link to the successfully authenticated Account will be returned:

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

You can use the returned href to GET the Account’s details (first name, last name, email, etc).

If the authentication attempt fails, you will see an error response instead:

{
  "status": 400,
  "code": 400,
  "message": "Invalid username or password.",
  "developerMessage": "Invalid username or password.",
  "moreInfo": "mailto:support@stormpath.com"
}

2.7. Next Steps

We hope you found this Quickstart helpful!

You’ve just scratched the surface of what you can do with Stormpath.

Want to learn more? Here are a few other helpful resources you can jump into.

  • Try out Stormpath in your favorite programming language with one of our language-specific quickstarts. Simply choose the integration of your choice, and then click on Quickstart.
  • Learn to easily partition user data in the Multi-Tenancy Chapter.
  • Easily support Google and Facebook Login by learning how Social Authentication Works.
  • Or simply jump into the next section and learn about Account Management.