Igniter Media

IgniterMedia.com & GracewayMedia.com are OAuth 2.0 providers. Use of the V2 API requires the client to have pre-registered an application to allow user authentication & authorization.

To describe the function of consuming our OAuth 2.0 API, we'll use this diagram taken from RFC 6749, the official word on OAuth.

In step A, we ask the authorization server to grant authorization to our client. The authorization server should prompt the user for recognition of this application; if granted, then access and refresh tokens are issued. The access token has a time-to-live value associated with it.

When downloading protected resources (steps C and D), the access token must be presented. If an expired or invalid token is presented, it will be rejected; the client should then attempt a refresh (step G.) If the refresh fails, client should start over from step A.

    
+--------+                                           +---------------+
|        |--(A)------- Authorization Grant --------->|               |
|        |                                           |               |
|        |<-(B)----------- Access Token -------------|               |
|        |               & Refresh Token             |               |
|        |                                           |               |
|        |                            +----------+   |               |
|        |--(C)---- Access Token ---->|          |   |               |
|        |                            |          |   |               |
|        |<-(D)- Protected Resource --| Resource |   | Authorization |
| Client |                            |  Server  |   |     Server    |
|        |--(E)---- Access Token ---->|          |   |               |
|        |                            |          |   |               |
|        |<-(F)- Invalid Token Error -|          |   |               |
|        |                            +----------+   |               |
|        |                                           |               |
|        |--(G)----------- Refresh Token ----------->|               |
|        |                                           |               |
|        |<-(H)----------- Access Token -------------|               |
+--------+           & Optional Refresh Token        +---------------+

Creating an Application

To get started, please reqeuest that an OAuth application be created for the sites on which you want to access protected resources. You will have to provide the callback URL your application will use to handle an access grant. When the application is created, you will then receive two magic numbers: a client_id and a client_secret. These two numbers will be used in your app, so store them appropriately.

Requesting the Grant

In order to prompt the user to grant the access, you need to open a browser window. In that browser window, make a request to the /oauth/authorize endpoint.

Arguments

api_domain: required; api.ignitermedia.com or api.gracewaymedia.com
client_id: required; The Client ID received in the previous step.
response_type: required; The string code
redirect_uri: required; The callback URI you provided when the application was created. These must match exactly or your request will be rejected.

Returns

Nothing...kinda.

No, really— what happens?

When the user grants access to your application, the registered callback URI will be triggered so you can receive our authorization code. When your server receives the callback, https://yourapp/opensesame?code=1928dbb28h... you are really only concerned with the value of the code query string parameter. That is your authorization code.

That authorization code is what you will exchange to get an access token!

GET /oauth/authorize

curl -X GET \
  -d "client_id={client_id}" \
  -d "response_type={response_type}" \
  -d "redirect_uri={redirect_uri}" \
  https://{api_domain}/oauth/authorize

N/A

Getting an Access Token

Post a request to the /oauth/token endpoint in order to retrieve a access and refresh token that you can use to access a protected resource (or refresh an expired access token).

client_id: required; The Client ID received when the application was created.
client_secret: required; The client secret received when the application was created.
redirect_uri: required; The callback URI you provided when the application was created.; required
grant_type: required; The string authorization_code in the initial access token request.
code: required; The authorization code received in the previous step, "Requesting the Grant."

Returns

An access token that can be used to access a protected resource; a refresh token that can be used to get another access token upon the expiration of the prior access token.

Parse out the access_token, refresh_token and expires_in values. The access_token is what you must set in HTTP headers when accessing a protected resource; it will expire in expires_in seconds. Once that period has passed, use the refresh_token to get a new access_token.

To this end, to keep from constant re-authorizing, the refresh_token should be persisted somewhere.

POST /oauth/token

curl -X POST \
  -d "client_id={oauth_application_id}" \
  -d "client_secret={oauth_secret}" \
  -d "redirect_uri={oauth_callback}" \
  -d "grant_type=authorization_code" \
  -d "code={authorization_code}" \
  https://api.ignitermedia.com/oauth/token

{
  "access_token" : "09ba487fc3df...",
  "token_type" : "bearer",
  "expires_in" : 7200,
  "refresh_token" : "8c488ab5f75d61..."
}

Using the Access Token

For each request to access a protected resource, you will need to add this HTTP header:

Authorization: Bearer {access_token}

Renewing the Access Token

When the access token expires, you will need to craft a POST request very similar to the one following the authorization grant.

client_id: required; The Client ID received when the application was created.
client_secret: required; The client secret received when the application was created.
redirect_uri: required; The callback URI you provided when the application was created.; required
grant_type: required; The string refresh_token.
refresh_token: required; The saved refresh token.

Returns

An access token that can be used to access a protected resource; a refresh token that can be used to get another access token upon the expiration of the prior access token. Note changes to the grant_type parameter and the replacement of the code parameter with refresh_token.

POST /oauth/token

curl -X POST \
  -d "client_id={oauth_application_id}" \
  -d "client_secret={oauth_secret}" \
  -d "redirect_uri={oauth_callback}" \
  -d "grant_type=refresh_token" \
  -d "refresh_token={refresh_token}" \
  https://api.ignitermedia.com/oauth/token

{
  "access_token" : "09ba487fc3df...",
  "token_type" : "bearer",
  "expires_in" : 7200,
  "refresh_token" : "8c488ab5f75d61..."
}

Get User Info

Retrieves authenticated user information.

Arguments

None.

Returns

Returns an object with the authenticated user's active membership information.

GET /v2/me.json

curl -H 'Authorization: Bearer {ouath_token}' \
https://api.ignitermedia.com/v2/me.json

{
  "id": 3,
  "email": "clint@ignitermedia.com",
  "name": "Clint Miller",
  "created_at": "2006-08-11T02:15:57.699-05:00",
  "updated_at": "2017-01-03T12:17:24.992-06:00",
  "active_membership": {
    "plan_code": "Freebie",
    "plan_name": "Free Membership",
    "plan_description": "No access to member-only content",
    "active": true
  }
}

Active Membership Metadata

The table below shows you the possible returned plan_* attributes for the active_membership part of the response.

`tenant`	`plan_code`	`plan_name`	`plan_description`
`igniter`	`Essentials`	`ESSENTIALS`	`If you just need the basics.`
`igniter`	`Starter`	`STARTER`	`If you just need the basics.`
`igniter`	`Premium`	`PREMIUM`	`All of our ready-made media.`
`igniter`	`Premium Pro`	`PREMIUM-PRO`	`If you want to create your own media.`
`graceway`	`Essentials`	`ESSENTIALS`	`If you just need the basics.`
`graceway`	`Starter`	`STARTER`	`If you just need the basics.`
`graceway`	`Premium`	`PREMIUM`	`All of our ready-made media.`
`graceway`	`Premium Pro`	`PREMIUM-PRO`	`If you want to create your own media.`

"V2" API Documentation

Authentication & Authorization

Creating an Application

Requesting the Grant

Arguments

Returns

No, really— what happens?

Getting an Access Token

Returns

Using the Access Token

Renewing the Access Token

Returns

User Credentials & Metadata

Get User Info

Arguments

Returns