User Authentication

Applications that want to query the Bluescape API must be authorized to do so by an active Bluescape user. Applications obtain this authorization using the OAuth flow which enables users to share access to their account without divulging their password.

Once authorized, applications receive access tokens from Bluescape which enable them to access Bluescape resources on behalf of the authorizing user. Changes made in Bluescape using these access tokens appear in the system as if made by the users themselves. Access tokens inherit the access rights of the user that authorized them, and thus, access tokens only enable applications to access and modify those resources in Bluescape that the user already has access to.

OAuth Flow

  1. When an application wishes to connect to Bluescape on behalf of a user, it directs that user to the authorization page on Bluescape's servers, identifying itself as the intended recipient of an access token tied to the user.
  2. On the authorization page, users give consent to providing an access token to the application by authenticating to their Bluescape account with their Bluescape credentials. Only Bluescape ever receives and validates the user's password.
  3. If user authentication is successful, Bluescape redirects the user back to the application along with a newly generated access token.
  4. The application extracts the access token ans stores it to use it until it expires or is renewed. Now the applciation is able to start querying the Bluescape API.
  5. Because access tokens expire after 2 weeks, applications must respond to 401 Unauthorized responses from the Bluescape API by initiating this flow again.

Step 1: Direct the User to Bluescape for Authorization

Applications requesting an access token should direct users to the authorization page at:

https://api.apps.us.bluescape.com/authorize

The following parameters should be URL-encoded and passed in the query string:

NAME REQUIRED DESCRIPTION
client_id Required Use the Client ID assigned to the application.
redirect_uri Required Use the Redirect URI provided in the application's settings.

The client_id can be obtained from your Developer Portal Account. After you sign in, go to the left list of options and select Applications. Here you will be able to create and generate new client_ids for your applications. Use the value under the CLIENT ID column as your client_id for thsi auhtentication process.

When users arrive to the authorization page they will be asked to log in to their Bluescape account. By entering valid Bluescape credentials, users will implicitly authorize the application to receive an access token connected to their account. Bluescape will then generate an access token for the application that uniquely bestows upon anyone who holds it access to impersonate the user in the name of the application.

IMPORTANT:
In the interest of everyone, developers must treat these access tokens with care. Remember that this token allows you to access all the workspaces your user has access to, and to add and delete objects from those workspaces.

Step 2: Implement Code that Extracts the Access Token

Once authorization is complete, Bluescape will redirect users back to the application along with the access token. Specifically, users will be sent to the Redirect URI specified in the application settings and the access token will be provided in the URL fragment (after the '#'). Applications will need to extract and store the access token before continuing the user experience. Note: server-side apps do not have visibility of the URL fragment and therefore cannot be responsible for extracting the access token.

Format of the incoming URL

<redirect_uri>#access_token=<access_token>&token_type=Bearer

Sample incoming URL

https://myapp.com/oauth/callback#access_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc...&token_type=Bearer

The URL fragment will contain the following parameters in query string format:

NAME DESCRIPTION
access_token The precious access token for connecting to the Bluescape API. Store it safely.
token_type Always has value Bearer.

Sample Javascript code to extract this fragment from the window.location:

<script>
  const params = {};
  const queryString = location.hash.substring(1);
  const regex = /([^&=]+)=([^&]*)/g;

  let match;

  while (match = regex.exec(queryString)) {
    params[match[1]] = match[2];
  }

  const accessToken = params.access_token;
  alert(accessToken);
</script>

Step 3: Using the Access Token

Access tokens enable applications to make requests of the Bluescape API. They are intended to be used as Bearer tokens and should be provided in the Authorization header of HTTP requests to the Bluescape API. The value of the header must be Bearer, a space, and the access token.

Example HTTP request:

curl -X GET https://api.apps.us.bluescape.com/session/user \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc...'

When initializing SDKs, the authorization parameter should contain the 'Bearer ' prefix.

const authorization = "Bearer " + accessToken;
const client = new Bluescape({ authorization });

Please remember, access tokens expire 2 weeks after they are issued. Requests made with expired access tokens will receive a 401 Unauthorized response from the Bluescape API. The proper response in this case is to restart the authorization flow with the user.

Full Example

Preconditions

NAME VALUE
Application Name My Bluescape App
Application Redirect URI https://my-bluescape-app.io/oauth/callback
Application Client ID a33e5f767
Application Whitelisted Domains https://my-bluescape-app.io

Authorization URL

https://api.apps.us.bluescape.com/authorize?client_id=a33e5f767&redirect_uri=http%3A%2F%2Fmy-bluescape-app.io%2Foauth2%2Fcallback

Callback URL

https://my-bluescape-app.io/oauth/callback#access_token=eyJhbGciOiJIUzI1NiIsImtpZCI6Imp3dF9zeW1tZXRyaWNfa2V5In0.eyJ1c2VyaWQiOiJIU0pHTTdUSFJIVUIiLCJleHAiOjE1MDE4OTI5MjgsInNjb3BlIjpbXSwiY2xpZW50X2lkIjoibk9oYnJPZW9HeHE4R2JBeFVvR2NIcXpEWmVqQWxxSUsiLCJhdWQiOiJodHRwczovL2F1dG9kZXNrLmNvbS9hdWQvand0ZXhwMTQ0MCIsImp0aSI6Im12bmwyZ2tKOEU4Tkd2S2JEVk00S3BHaTRCYkZtRndyUmVrd2NjT3B3RU1OTlVTdnZrNnljNllWSGo3d29WWjMifQ.Niy8dwBQVuhcaCTClZqttJleuKIoQtnS8yoT1ZJWgNg&token_type=Bearer

Access Token (extracted from the callback url)

eyJhbGciOiJIUzI1NiIsImtpZCI6Imp3dF9zeW1tZXRyaWNfa2V5In0.eyJ1c2VyaWQiOiJIU0pHTTdUSFJIVUIiLCJleHAiOjE1MDE4OTI5MjgsInNjb3BlIjpbXSwiY2xpZW50X2lkIjoibk9oYnJPZW9HeHE4R2JBeFVvR2NIcXpEWmVqQWxxSUsiLCJhdWQiOiJodHRwczovL2F1dG9kZXNrLmNvbS9hdWQvand0ZXhwMTQ0MCIsImp0aSI6Im12bmwyZ2tKOEU4Tkd2S2JEVk00S3BHaTRCYkZtRndyUmVrd2NjT3B3RU1OTlVTdnZrNnljNllWSGo3d29WWjMifQ.Niy8dwBQVuhcaCTClZqttJleuKIoQtnS8yoT1ZJWgNg

If you have any questions or comments, please contact us at Bluescape support.