| Developer Portal

Help Center

Authentication and Authorization

This guide covers:

Overview

The Firstup API authentication model is based on OAuth 2.0. Every request must provide an access token. This token identifies the authenticated user, if any, and the program. The user can have any role because different endpoints are intended to provide capability for varying use cases. Making requests using an access token is effectively the same as carrying out operations through Program Studio or through the mobile apps as a logged-in user.

To request access to the API, contact support at support@socialchorus.com.

User authentication and OAuth token requests are handled by an auth server separate from the Partner API’s domain. The url for the auth service is https://auth.socialchorus.com.

Security Considerations

You will be assigned a “Client ID” and a “Client Secret” by Firstup. Protect all credentials and tokens carefully and be especially careful with Client Secret. Notify Firstup immediately if you believe there is any chance these values have been compromised and we will be happy to replace them.

Access tokens expire after 2 hours. Authorization codes expire in 10 minutes. Refresh tokens are valid as long as the client app is registered with the authorization server and the user continues to give it consent.

Program Scoping

The Firstup Partner API is always used in the scope of a single program. Although a user may have membership in multiple programs, an access token is associated to a single program. Any client wishing to operate against multiple programs ( even with the same user) must use different access tokens for each program, where the token corresponds to the program being operated against in a given request.

Use an OAuth 2.0 library

Adopting one of the many available OAuth 2.0 libraries is the easiest way to create a robust client. The OAuth community maintains a list of some of the libraries available at https://oauth.net/code/#client-libraries.

This guide is intended to provide helpful background on the theory of how the authorization system works to aid in troubleshooting and testing, but we recommend the use of a mature library for production applications.

Selecting a Grant Type

Firstup supports two OAuth 2.0 grant flows for use with the Partner API: “Authorization Code” and “Client Credentials”. Authorization Code flow requires a user to login and consent to use of their data, while Client Credentials only requires the Client ID and Client Secret and does not inherently identify a user. Use of either flow produces an access token that is used when making requests to the Firstup API.

If you will be working with endpoints that require a user context, including any of the Feeds endpoints, you should use the Authorization Code grant flow. Otherwise, you can use either grant flow and may prefer the Client Credentials grant flow due to its simplicity.

When interacting with a feed, a client using the client credentials grant flow will act as a guest. For content endpoints, a client using the client credentials grant flow will act as a program manager. When using the authorization code grant flow, the client will act as the role of the authenticated user.

Auth Scope List

The following is a list of all possible auth scopes that can be requested for an access token. The required scopes for each endpoint are listed in the API Endpoint Reference. If scopes are not specified in the auth request, the default scopes for your OAuth application will be granted.

Scope Description
admin_login Login using an admin login ui. (Uncommon)
content.read View and list details of content in your program.
content.write Create, view, and update content in your program.
content.videos.download Download video content from content posts.
content.replication.audit View content replication status associated with manageable content in your program.
feeds.read View your feeds.
feeds.rendered.read View rendered content from feed posts.
feeds.engage View your feeds and engage with posts (likes, bookmarks, etc).
openid View the authenticated user's OpenID profile information.
profile View your basic profile information.
email View your email addresses.
address View your physical addresses.
phone View your phone numbers.
employment View your employment information.
public View the authenticated user's profile information.
users.read View and list details of users in your program.
users.write Create, view, and update users in your program.
groups.read View and list details of groups in your program.
groups.write Create, view, and update groups in your program.
webhooks.read View and list details of webhook subscriptions in your program.
webhooks.write Create, view, and update webhook subscriptions in your program.

How to use authorization code grant to get access and refresh tokens

The Authorization Code grant flow produces the most versatile tokens because it associates the tokens with a user allowing the use of user-centric actions such as “like content item.” This flow breaks down as follows:

  1. Sign in to the auth server
  2. Give consent to the app
  3. Request access token
  4. Use access token to make API calls
  5. Use refresh token to renew access token
  6. Repeat steps 4 and 5 as desired

In more detail, that is:

1. Using a web browser: Sign in, give consent, and retrieve your authorization token from:

https://auth.socialchorus.com/oauth/authorize?
client_id=<CLIENT ID>&
redirect_uri=https://auth.socialchorus.com/oauth/authorize/native&
scope=openid%20public&
state=<CSRF_TOKEN>&
response_type=code

Where <CSRF_TOKEN> is an arbitrary value that the client should create and check for in the response to ensure authenticity.

Sample request:

https://auth.socialchorus.com/oauth/authorize?client_id=c3aa8631a3c9bd72581cef94b13e2dc7c5d09e278adad1174b8f4e7749b81b3e&
redirect_uri=https://auth.socialchorus.com/oauth/authorize/native&
scope=openid%20public&
state=mySUPER$3cRe7&
response_type=code

The page will look like this:

Image of authorization request's response

Note: If your app uses a different page for its redirect_uri, the authorization code can be found in the “code” query parameter of the URL you are redirected to after signing in and giving consent.

2. Submit your token request in the form:

curl -X POST \
https://auth.socialchorus.com/oauth/token                            \
-F grant_type=authorization_code                                     \
-F redirect_uri=https://auth.socialchorus.com/oauth/authorize/native \
-F client_id=<CLIENT ID>                                             \
-F client_secret=<CLIENT SECRET>                                     \
-F code=<AUTHORIZATION CODE>

Note: https://auth.socialchorus.com uses cookies to streamline the login process. If you are having trouble logging in, clear your cookies related to that site.

Sample request:

curl -X POST \
https://auth.socialchorus.com/oauth/token \
-F grant_type=authorization_code \
-F redirect_uri=https://auth.socialchorus.com/oauth/authorize/native \
-F client_id=fdf245738eb201e4ede5acff86d8552aa60c9afb30e45111ab9fa9054f31deb6 \
-F client_secret=cdef2738c0592f2daa516718f3be12d0d9ee2f9137832e333da7bdd105d43bd1 \
-F code=005c287916b62107a6ff04d970f5c4e996059cb31f820c83bc4bd0e39419437a

Sample response:

{
  "access_token": "8ff789b389b3756f90d77c34fc3e2135964ccc4e3e7e6c4609e10fee5efc8dc5",
  "token_type": "Bearer",
  "expires_in": 7200,
  "refresh_token": "ad1f9f4dc7d34385537e03f223873958571e54992ce10b83ac3b52f16b0e7c88",
  "scope": "openid public",
  "created_at": 1539732223,
  "id_token": "eyJ0eXAiOiJ...Aq3DxK23w",
  "realm": "program:1"
}

How to use client credentials to get access and refresh tokens for non-user interactions

When an end-user is not required, the Client Credentials grant can be used to fetch an access token. It grants role-based access using the Client ID and Client Secret. Be careful with contexts in which Client Credentials grant is being used, as it effectively makes requests with the same permissions as a Program Manager. This may be ideal for working with some endpoints, such as those in the Content Publishing section, but does not work at all with endpoints that require an end user, such as those in the Feeds section that use the authenticated user to determine which content items are visible and to attribute interactions (such as likes and bookmarks).

At a high level, use of this grant type will consist of:

  1. Request access token
  2. Use access token to make API calls
  3. Repeat steps 1 and 2 as desired

In more detail, that is:

Request format:

curl -X POST \
https://auth.socialchorus.com/oauth/token \
-F grant_type=client_credentials \
-F client_id=<CLIENT ID> \
-F client_secret=<CLIENT SECRET>

Sample request:

curl -X POST \
https://auth.socialchorus.com/oauth/token \
-F grant_type=client_credentials \
-F client_id=fdf245738eb201e4ede5acff86d8552aa60c9afb30e45111ab9fa9054f31deb6 \
-F client_secret=cdef2738c0592f2daa516718f3be12d0d9ee2f9137832e333da7bdd105d43bd1

Sample response:

{
  "access_token": "6fcb9647ace549e0208bb31dc581a4c4bc204032ab6694e73de77e611d77b23c",
  "token_type": "Bearer",
  "expires_in": 7200,
  "scope": "public",
  "created_at": 1539746984,
  "realm": "program:1"
}

Using your access token

All requests must provide an Authorization header. The bearer token format used by the OAuth 2.0 standard is:

Authorization: Bearer <ACCESS TOKEN>

Where <ACCESS TOKEN> is replaced with an access token for the acting user.

For example:

curl -H "Authorization:Bearer <ACCESS TOKEN>" 'https://partner.socialchorus.com/v2/content'

If OAuth requirements are not met, 401 (user in token not found) or 403 (insufficient permission) responses are returned.

How to use OAuth PKCE to get an access token

PKCE is an extension to the Authorization Code flow to prevent CSRF and authorization code injection attacks.

The process is similar to standard access generation with the addition of requiring some additional URL parameters when redirecting to the authorization server and the generation of those parameters.

PKCE was designed to allow mobile and single-page apps (SPAs) a secure sign-in mechanism when a client secret can't be kept... secret. Firstup's authorization server supports PKCE.

Overview

To sign in using PKCE the client must generate "code verifier" and "code challenge" tokens. There are libraries available for this for most languages, and some OAuth client libraries have PKCE capabilities "baked in".

The code verifier should be cryptologically random. The code verifier is used to generate an authorization URL parameter. The code challenge is the code verifier, SHA256-hashed, and Base64-encoded.

Subsequent request(s) for access tokens use the hashed, encoded code verifier. While the PKCE spec does allow for "plain" code challenges (not hashed and encoded), the Firstup authorization server does not.

Getting Authenticated

Once the code challenge and code verifier tokens are generated the URL for the Firstup authorization server can be generated. It expects to receive the following parameters:

Parameter Description
client_id The application's configured Client ID.
redirect_uri The application's configured redirect URI.
scope One or more of the scopes, as restrictive as possible.
state A nonce that can be used to verify the response.
code_challenge The generated code challenge.
code_challenge_method "S256" Only "S256" is supported.
program_id Program ID
response_type "code"
response_mode "query"

Example URL (with parameters broken out for clarity):

https://auth.socialchorus.com/oauth/authorize
?client_id=example_spa
&redirect_uri=https%3A%2F%2Flocalhost%3A8666%2Fauth_callback.html
&scope=openid+profile+feeds.read+feeds.rendered.read+feeds.engage+content.read+admin_login+content.videos.download
&state=1234
&code_challenge=9s1f7fGkMBO7CVoyFHQ8jdqoqbgzfNUt-P4B3Ixzwfo
&code_challenge_method=S256
&program_id=1
&response_type=code
&response_mode=query

Visiting this URL begins the Firstup login process. Once that process has completed successfully the Firstup authorization server will redirect back to the application's configured redirect URI.

Requesting an access token

The application's callback URI will receive two parameters:

Parameter Description
state The state nonce supplied in the initial URL.
code The token to use when requesting the access token.

If the state parameter does not match what was sent, something horrible has happened. Since PKCE parameters themselves provide CSRF protection, it is not strictly necessary and may be used to keep application state, but it should still match.

Requesting the access token requires the following parameters, which includes the code token returned to the application's redirect URI:

Parameter Description
code The code returned via the application's callback URI parameters.
code_verifier The code verifier generated in the first step.
client_id The application's Client ID.
redirect_uri The application's callback URI.
grant_type "authorization_code"

Access token response

The JSON response from this URL will contain an access_token property. The value of this property is the access token used to make requests to Partner API endpoints as described in this document (assuming the user has access and the requested scopes allow the operation).

This token is used in an authorization header as a bearer token:

Authorization: Bearer <access_token value>

How to refresh an access token

Access Tokens expire after two hours. Once you receive your initial access token via authorization code, you can create subsequent tokens using the refresh grant. Access tokens produced by the refresh grant have the same rights and privileges as access tokens produced using the grant flow that produced the refresh token.

Note: Client Credentials grant does not provide a refresh token. When a Client Credentials grant access token expires, repeat the Client Credentials grant flow.

The request is formatted as:

curl -X POST \
https://auth.socialchorus.com/oauth/token \
-F grant_type=refresh_token \
-F client_id=<CLIENT ID> \
-F refresh_token=<REFRESH TOKEN>

Where is the “refresh_token” from a previous authentication request.

Sample request:

curl -X POST \
https://auth.socialchorus.com/oauth/token \
-F grant_type=refresh_token \
-F client_id=fdf245738eb201e4ede5acff86d8552aa60c9afb30e45111ab9fa9054f31deb6 \
-F refresh_token=ad1f9f4dc7d34385537e03f223873958571e54992ce10b83ac3b52f16b0e7c88

Sample response:

{
  "access_token": "f574ecddd18be52a2a6ed0485e8a6c47e5ef192b005fed400c90657b9b57cc7f",
  "token_type": "Bearer",
  "expires_in": 7200,
  "refresh_token": "ef9ba00b28f270784cc34c1ad500ae2d112c95b214bed0172ea642a482671913",
  "scope": "openid public",
  "created_at": 1539616951,
  "id_token": "eyJ0eXAiOiJ...MvuurumUQ",
  "realm": "program:1"
}

Definitions

Term Definition
Access Token A string that identifies the authenticated client app, the authenticated user, and the user’s authorization of their data to allow access to resources on the Firstup API.
Authenticated User The user account that generated the authorization code.
Authorization code A string of characters that identifies a user’s consent to allowing a client app to use their data in the Firstup platform.
Client App An app that is registered with the authentication system so that it can interact with the Firstup API.
Consent A user’s approval for an app to access their account and act on their behalf.
Client ID A string that identifies the client app to the authorization system
Client Secret A string that confirms the authenticity of the client app. Analogous to a password.
Code Challenge Hashed, encoded version of the Code Verifier used in the OAuth PKCE flow.
Code Verifier Cryptologically-random OAuth PKCE token used to generate an authorization URL parameter.
CSRF Token A string generated by the initiating party in a transaction to allow the authenticity of the response to be verified.
Grant type The authentication strategy for receiving access tokens. One of: authorization_code, client_credentials, or refresh_token.
PKCE Proof Key for Code Exchange, an OAuth 2.0 authorization code flow.
Refresh token A hash provided as part of an authentication response that allows a new access token to be generated without repeating the authentication step.
Scope The categories of actions a token is intended to have the ability to perform.

Documentation