NAV Navbar

Introduction

Welcome to the Steady API!

You can use our API to obtain limited read access to Steady user accounts in the scope of your project. Our API is designed following the JSON API specification.

We implement the OAuth 2.0 authorization framework so that you can get access to Steady on behalf of the user, if the user approves that.

With our API endpoints, only accessible via HTTPS, you have access to the user entity as well as the subscription status of the user. Based on this information you can implement authorization for the user in your application.

You can view code examples in the dark area to the right, and see example response data for each request.

OAuth 2.0

Create your app

Before you can begin the OAuth process, you must first register a new app with Steady. You can do this in your Steady backend for the project (OWN PROJECTS -> PROJECT -> INTEGRATE -> API).

Client ID and Client Secret

Once your application is registered, Steady will issue “client credentials” in the form of a client identifier and a client secret. The Client ID is a publicly exposed string that is used by the Steady API to identify your application, and is also used by you to build authorization URLs that are presented to users in your application. The Client Secret is used to authenticate the identity of your application when your application requests to access a user’s account, and must be kept private between your application and the API.

Authorization Grant

The first steps in the OAuth 2.0 flow are about obtaining an authorization grant and access token for a user.

Grant Type: Implicit

We don’t offer this flow for clients which cannot use a client secret (e.g. Single Page Apps). Please use Authorization Code grant without client secret for better security.

Grant Type: Authorization Code

The authorization code grant type is the most commonly used because it is optimized for server-side applications, where source code is not publicly exposed, and the client secret can be maintained confidentiality. This is a redirection-based flow, which means that the application must be capable of interacting with the user-agent (i.e. the user’s web browser) and receiving API authorization codes that are routed through the user-agent.

Authorization Code Flow

  https://steadyhq.com/oauth/authorize?
    response_type=code&
    client_id=CLIENT_ID&
    redirect_uri=REDIRECT_URI&
    scope=read&
    state=RANDOM_STRING

Create an authorization link, which sends your user to Steady:

https://steadyhq.com/oauth/authorize?response_type=code&client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&scope=read&state=RANDOM_STRING

Parameter Value
response_type code specifies that your application is requesting an authorization code grant
client_id the CLIENT_ID can be found in the Steady Backend
redirect_uri the REDIRECT_URI you have set in the Steady Backend. After authorization Steady will redirect the user-agent to this URI.
scope read specifies the level of access your application is requesting
state a RANDOM_STRING generated by your application, which you’ll verify later

Step 2: User authorizes your application at Steady

When the user clicks the link, they must first log in to Steady, to authenticate their identity (unless they are already logged in). When the scope is set to read the user is authorized automatically in order to achieve a smooth user experience. Otherwise the user will be prompted by Steady to authorize or deny your application access to their account. Here is an example authorize application prompt:

Step 3: Your application receives an authorization code

  https://your-website.com/oauth/callback?
    code=AUTHORIZATION_CODE&
    state=RANDOM_STRING

If the user gives the authorization, Steady redirects the user-agent to your application redirect URI, which was specified during the client registration, along with an authorization code. The redirect would look something like this:

https://your-website.com/oauth/callback?code=AUTHORIZATION_CODE&state=RANDOM_STRING

Parameter Value
code authorization code you use to request an access token
state the same state value you passed in before

Step 4: Your application requests the access token

POST /api/v1/oauth/token HTTP/1.1
Accept: application/json
Host: steadyhq.com
{
  "client_id": CLIENT_ID,
  "client_secret": CLIENT_SECRET,
  "grant_type": "authorization_code",
  "code": AUTHORIZATION_CODE,
  "redirect_uri": REDIRECT_URI
}

The application requests an access token from the Steady API, by passing the authorization code along with authentication details, including the client secret, to the API token endpoint.

https://steadyhq.com/api/v1/oauth/token

Parameter Value
client_id the CLIENT_ID can be found in the Steady Backend
client_secret the CLIENT_SECRET can be found in the Steady Backend. Optional.
grant_type authorization_code specifies that this request is within an Authorization Code grant flow
code the AUTHORIZATION_CODE received in Step 3
redirect_uri the REDIRECT_URI you have set in the Steady Backend

Step 5: Your application receives the access token

HTTP/1.1 201 CREATED
Content-Type: application/json; charset=utf-8
{
  "access_token": "V1JvWWVXdHcxajkzK1FBdDRwSS95UT09",
  "refresh_token": "MXpyNWRJRUdaMHg0aW9MM2ZJb1lVQT09"
  "token_type": "bearer",
  "expires_in": 604800,
  "scope": "read",
  "info": {
    "id": "5e7607b0-1458-41e4-b6bc-e6301c39e7da",
    "first-name": "Jane",
    "last-name": "Doe",
    "email": "jane.doe@example.com"
  }
}

If the authorization request from Step 4 is valid, Steady will send a response containing the access token.

Parameter Value
access_token the access token issued by Steady
refresh_token the refresh token issued by Steady / null
token_type the type of the token issued (bearer)
expires_in time in seconds until the access token expires
scope specifies the level of access granted
info the basic user information

Refresh the access token

POST /api/v1/oauth/token HTTP/1.1
Accept: application/json
Host: steadyhq.com
{
  "client_id": CLIENT_ID,
  "client_secret": CLIENT_SECRET,
  "grant_type": "refresh_token",
  "refresh_token": REFRESH_TOKEN,
  "redirect_uri": REDIRECT_URI
}

If a refresh token was issued, it may be used to request new access tokens if the original token has expired. Steady only issues a refresh token if you send the client secret along in Step 4. Make your request to refresh the access token to this endpoint:

https://steadyhq.com/api/v1/oauth/token

Parameter Value
client_id the CLIENT_ID can be found in the Steady Backend
client_secret the CLIENT_SECRET can be found in the Steady Backend.
grant_type refresh_token
refresh_token the REFRESH_TOKEN received in Step 5
redirect_uri the REDIRECT_URI you have set in the Steady Backend
  https://steadyhq.com/your_campaign_page?
    oauth_client_id=CLIENT_ID

If you use the following link to send your users to your Steady campaign page - and they complete the subscription - the user is authorized automatically and the flow will continue with Step 3.

https://steadyhq.com/your_campaign_page?oauth_client_id=CLIENT_ID

Parameter Value
oauth_client_id the CLIENT_ID can be found in the Steady Backend

Authorization

To authorize, add “Authorization” as request header field.

GET /api/v1/users/me HTTP/1.1
Accept: application/vnd.api+json
Authorization: Bearer OAUTH2_ACCESS_TOKEN
Host: steadyhq.com

Make sure to replace OAUTH2_ACCESS_TOKEN with the access token of the user you make the request for.

Steady relies on bearer tokens in the “Authorization” request header field.

Authorization: Bearer OAUTH2_ACCESS_TOKEN

Users

Current basic data

GET /api/v1/users/me HTTP/1.1
Accept: application/vnd.api+json
Authorization: Bearer OAUTH2_ACCESS_TOKEN
Host: steadyhq.com
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json; charset=utf-8
{ 
  "data": {
    "type": "user",
    "id": "5e7607b0-1458-41e4-b6bc-e6301c39e7da",
    "attributes": {
      "first-name": "Jane",
      "last-name": "Doe",
      "email": "jane.doe@example.com"
    }
  }
}

GET https://steadyhq.com/api/v1/users/me

Returns the current basic user data for the user associated with the access token.

Needed scope of access_token:

read

Attributes

Attribute Description
first-name first name of the user
last-name last name of the user
email email address of the user

Subscriptions

Current status

GET /api/v1/subscriptions/me HTTP/1.1
Accept: application/vnd.api+json
Authorization: Bearer OAUTH2_ACCESS_TOKEN
Host: steadyhq.com
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json; charset=utf-8
{ 
  "data": {
    "type": "subscription",
    "id": "8ef509c7-b8fe-4a56-a366-fadf030bfc64",
    "attributes": {
      "state": "not_renewing",
      "cancelled-at": "2017-05-01T22:00:14.000000Z",
      "expires-at": "2017-05-18T10:55:31.000000Z",
      "monthly-amount-in-cents": 1000,
      "period": "monthly"
    }
  },
  "included": [{
    "type": "plan",
    "id": "b9d7574f-5246-4c94-ade5-1d4e9b169afc",
    "attributes": {
      "name": "Gold plan",
      "image-url": "https://steady.imgix.net/gfx/steady_logo.svg"
    }
  }]
}

GET https://steadyhq.com/api/v1/subscriptions/me

Returns the current subscription status for the user associated with the access token.

Needed scope of access_token:

read

Subscription attributes

Attribute Description
state active / not_renewing
cancelled-at datetime of the cancellation / null
expires-at datetime when the subscription will expire / null
monthly-amount-in-cents amount the user pays per month in cents
period monthly / annual — the period of the contract of the user

Plan attributes

Attribute Description
name name of the plan
image-url plan image url / null