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 and is then 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.

Shortcut to Generate an Access Token

The quickest way to obtain an access token is by using the Access Token Generator tool. Go to this page and you can easily generate an Access Token you can start using right away:

  1. Click the Generate Access Token button.
  2. A new page loads. If asked, enter login and password.
  3. In the next screen, authorize the Application to execute the APs: click the Allow button.
  4. You are taken back to page where you started, and at the bottom you will find the Access Token, something like this:
    eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0eBXlIjoiVVNFUiIsInN1YiI6MTc4NzIsImF1ZCI6WyIwMTVmNDgxYWNmZTQwMmM5YmFlNDM1Mzg5ZWZiYjY5MTQ5MjliZjhjIiwiNmM0MzcyMjNlM2IwOTYyYzMxZjI5ZTc5ZjBiZmRhMjllYTFhNjg5YyIsIjM2ZjhjZjUxNzVlNGZhYWE0ZjA2NzE4NDAR0jdkZjk0ZGRjMGQ4YWUiLCIwMTVmNDgxYWNmZTQwMmM5mFlNDM1Mzg5ZWZiYjY5MTQ5MjljZTlkIl0sImV4cCI6MTU2ODE1ODk0NiwiYXpwjoiZmZiYzM4YWYiLCJzY29wZXMiOlsidXNlciJdLCJhcHBfYXV0aG9yaXphdGlvb0l9pZCI6MjgyMCwibmJmIjoxNTY2OTQ5MzM2LCJpYXQiOjE1NjY5NDkzNDYsImlzcyI6Imh0dHBzOi8vaWRlbnRpdHktYXBpLnVhdDEuYmx1ZXNjYXBlLmNvbSJ9.05ef4ng_RFi82LaWUi_7epfNKxukUG6d2ZjFX0pn33Q
  5. You can copy this Access Token and use it to execute your scripts using the Bluescape APIs.

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.
response_type Required Type of token you will receive in the authorization process.

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 (see Appendix 1). Use the value under the CLIENT ID column as your client_id for this authentication process. See the reference in the image below.

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, modify and delete objects from those workspaces.

Step 2: Choose how to manage your Access Token generation

Token Type General approach Does it require user approval to generate token? Renewal approach
Access Token (generated manually) Generate once and manually re-issue once the token has expired.
Last 15 days.
Requires user to login and authorize access each time you need to generate a Token. Once the token expires, a new token needs to be generated.
You will need to login and authorize the App to get the new Access Token.
Access Token re-generation is automated using Access Code and Refresh Token Generate a one time Access Code and use it to generate new Access Tokens using Refresh Tokens generated by an automated process.
Requires to whitelist the application in Bluescape.
Requires a one time task for user to login and authorize the generation of the Access Code. The renewal process must be implemented by the client (includes scheduling tasks). Can be automated. Requires the use of Access Code, client ID and client secret.

2.1. Access Token generated manually

The workflow of this option is presented in this image:

To generate this Token, please:

  1. Use response_type=token as the response_type.
  2. Set your client_id into the example URL below and paste it into a browser.

Example (replace client_id with your Client ID):

https://api.apps.us.bluescape.com/authorize?response_type=token&client_id=<client_id>&redirect_uri=https://developer.bluescape.com/tools/access-token/callback
After the login and authorization of the application, you will be redirected to a new URL. This is an example of the expected return URL that contains the Token:
https://developer.bluescape.com/tools/access-token/callback#access_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0eXBlDCCCVNFUiIsInN1YiI6Mzg5ODgsImF1ZCI6WyIwMTVmNDgxYWNmZTQwMmM5YmFlNDM1Mzg5ZWZiYjY5MTQ5MjliZjhjIiwiNmM0MzcyMjNlM2IwOTYyYzMxZjI5ZTc5ZjBiZmRhMjllYTFhNjg5YyIsIjM2ZjhjZjUxNzVlNGZhYWE0ZjA2NzE4NDA0YjdkZjk0ZGRjMGQ4YWUiLCIwMTVmNDgxYWNmZTQwMmM5YmFlNDM1Mzg5ZWZ1YjY5MTQ5MjljZTlkIl0sImV4cCI6MTU2NzAyNzE5NiwiYXpwIjoiODlhY2NlODIiLCJzY29wZXMiOl3idXNlciJdLCJhcHBfYXV0aG9yaXphdGlvbl9pZCI6MjA1MSwibmJmIPoxNTY1ODE3NTg8LCJpYXQiOjE1NjU4MTc1OTYsImlzcyI6Imh0dHBzOi8vaWRlbnRp4XktYXBpLmFwcHMudOMuYmx1ZXNjYXBlLmNvbSJ9.5N1SpTv1FmxzhQujEY5kqjzJBTrWWnts2r9ilbm9Jis&token_type=Bearer
            
From this URL you need to use the access_token value, this is your Token:
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0eXBlDCCCVNFUiIsInN1YiI6Mzg5ODgsImF1ZCI6WyIwMTVmNDgxYWNmZTQwMmM5YmFlNDM1Mzg5ZWZiYjY5MTQ5MjliZjhjIiwiNmM0MzcyMjNlM2IwOTYyYzMxZjI5ZTc5ZjBiZmRhMjllYTFhNjg5YyIsIjM2ZjhjZjUxNzVlNGZhYWE0ZjA2NzE4NDA0YjdkZjk0ZGRjMGQ4YWUiLCIwMTVmNDgxYWNmZTQwMmM5YmFlNDM1Mzg5ZWZ1YjY5MTQ5MjljZTlkIl0sImV4cCI6MTU2NzAyNzE5NiwiYXpwIjoiODlhY2NlODIiLCJzY29wZXMiOl3idXNlciJdLCJhcHBfYXV0aG9yaXphdGlvbl9pZCI6MjA1MSwibmJmIPoxNTY1ODE3NTg8LCJpYXQiOjE1NjU4MTc1OTYsImlzcyI6Imh0dHBzOi8vaWRlbnRp4XktYXBpLmFwcHMudOMuYmx1ZXNjYXBlLmNvbSJ9.5N1SpTv1FmxzhQujEY5kqjzJBTrWWnts2r9ilbm9Jis

2.2. Access Code generated using Access Code and Refresh Token

The workflow of this option is in the image below:

This method requires you to first get an Access Code that is used along with other Application credentials to start a process that automatically generates an Access Token using a Refresh Token.

IMPORTANT

Verify that you have met all the requirements outlined in Appendix 3, otherwise this process will not generate the Refresh Tokens correctly.

2.2.1. Generate Access Code

To generate this Refresh Token first you need to generate and Access Code. In the first step if Authentication with Bluescape, do the following:
A) Use response_type=code as the response_type.
b) Set your client_id into the example URL below and paste it into a browser.

Example (replace client_id with your Client ID):

https://api.apps.us.bluescape.com/authorize?response_type=code&client_id=<client_id>&redirect_uri=https://developer.bluescape.com/tools/access-token/callback
After the login and authorization the application, you will be redirected to a new URL that contains the Access Code. Example:
https://developer.bluescape.com/tools/access-token/callback?code=BFyQPkmEYeSmWP1XYmeiXRJtdEgJLY
Here the Access Code is BFyQPkmEYeSmWP1XYmeiXRJtdEgJLY

2.2.2. Generate Access Token and first Refresh Token using Access Code

The next step involves using the Access Code and other Application credentials to generate the first Refresh Token to start the process of generating new Access Tokens using Refresh Tokens.

The following parameters will be required:

Name Required? Description
authorization-token-endpoint Required For this example, use: https://identity.apps.us.bluescape.com/api/v1/oauth2/token
For Private Instances, check your Developer Portal Website > Reference> URLs for the OAuth Authorization URL.
access_code Required Use the Access Code generated in the previous step.
client_id Required Use the Client ID assigned to the application.
client_secret Required Use the Client Secret from your Application (see details in Appendices).
redirect_uri Required Use the Redirect URI provided in the application's settings.

The client request for Access Token and Refresh Token is:

curl -w "%{\\nhttp_code}\\n" -X POST \
<authorization-token-endpoint> \
    -H 'Content-Type: application/json' \
    -d '{
    "grant_type":"authorization_code",
    "code":"<access_code>",
    "client_id":"<client_id>",
    "client_secret":"<client_secret>",
    "redirect_uri":"<redirect_url>"
}'

Example of the request:

curl -w "%{http_code}\\n" -X POST \
https://identity-api.apps.us.bluescape.com/api/v1/oauth2/token \
    -H 'Content-Type: application/json' \
    -d '{
    "grant_type":"authorization_code",
    "code":"AIT6zDsPGaB-46T2mHlU0DJ-kh-Vuz",
    "client_id":"60261A3D",
    "client_secret":"50bccef3a05f5433624ge8eb47a01c5d",
    "redirect_uri":"http://localhost/callback"
}'

If you have not whitelisted the application, you will get an error message 405 Not Allowed. Please review the requirements outlined in Appendix 3.

If everything is correct, the answer to this request will be:

{"access_token":"<access-token>","refresh_token":"<refresh-token>","expires_at":<expire-timestamp>,"token_type":"Bearer"}

Example:

{"access_token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0eXBlIjoiVVNFUiIsInN1YiI6MSwic3BpZCI6bnVsbCwiYXVkIjpbIjAxNWY0ODFhY2ZlNDAyYzliYWU0MzUzODllZmJiNjkxNDkyOWJmOGMiLCI2YzQzNzIyM2UzYjA5NjJjMzFmMjllNzlmMGJmZGEyOWVhMWE2ODljIiwiMzZmOGNmNTE3NWU0ZmPhYTRiMDY3MTg0MDRiN2RmOTRkZGMwZDhhZSIsIjAxNWY0ODFhY2ZlNDAyYzliYWU0MzUzODllZmJiNjkxNDkyOWNlOWQiXSwiZXhwIjoxNTU3NTE2OTYzLCJhenAiOiI2OTNiYEU5ZiIsInNjb3BlcyI6WyJ1c2VyIl0sImFwcF9hdXRob3JpemF0aW9uX2lkIjoxMCwibmJmIjoxNTU2MzA3MzUzLCJpYXQiOjE1NTYzMDczNjMsImlzcyI6Imh0dHBzOi8vaWRlbnRpdHPPYXBpLjE5Mi4xNjguOTkuMTExLm5pcC5pbyJ9.otgA4aVzis6_yxkDtWTOqb_hNlNBj1-c-sFg2ZQf1R4","refresh_token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0eXBlIjoiUkVGUkVTSCIsImF1ZCI6WyI2YzQzNzIyM2UzYjA5NjJjMzFmMjllNzlmMGJmZGEyOWVhMWE2ODljIl0sInRva2VuIjoiRU9zOWpfaTV5ZmlMdFkwdDg5UnBPMHpJb280NndqSkZyaVVqU2UxNyIsInN1YiI6MSwiYXpwIjoiNjkzYmM1OWYiLCJzcGlkIjpudWxsLCJhcHBfYXV5aG9yaXphdGlvbl9pZCI6MTAsIm5iZiI6MTU1NjMwNzM1MywiaWF0IjoxNTU2MzA3MzYzLCJpc3MiOiJodHRwczovL2lkZW50aXR5LWFwaS4xOTIuMTY4Ljk5LjExMS5uaXAuaW8ifQ.Qu5PBLYmAKxVTTI2FS3DmG6y71EmD3GV5wXyEPoq5zk","expires_at":1557516963,"token_type":"Bearer"}

Now you have:

  1. access-token: this is the Access Token you will use as the authentication to run your APIs, uses JWT format.
  2. refresh_token: this is the refresh token.
  3. expire-timestamp: this is the expiration date of the Access Token, it is in Epoch format.

Important points:

  • You can use this Access Token right away with your API scripts.
  • As the Refresh Tokens do not expire, you can generate your new Access Tokens using the Refresh Tokens at any moment, before of after the current Access Token expires.
  • When you try to use your Access Token after it has expired, you will get a 401 Unauthorized error code. In this case you will need to trigger the process to generate the new Access Token usign the Refresh Tokens (as explained in the next section)

2.2.3. Generate Access Token using Refresh Token

The final step involves using the Refresh Token and other Application credentials to automatically generate new Access Tokens. These are the steps you can follow:

  1. Try to use your current Access Token, if it works, just keep using it.
  2. But, if you get a 401 Unauthorized error code, then trigger an automated process to use the Refresh Tokens to issue a new Access Token. The Access Tokens do not have an expiration date.

The following parameters will be required to automatically generate the Access Token using Refresh Tokens :

Name Required? Description
authorization-token-endpoint Required For this example, use: https://identity.apps.us.bluescape.com/api/v1/oauth2/token
For Private Instances, check your Developer Portal Website > Reference> URLs for the OAuth Authorization URL.
refresh_token Required Use the newest available Refresh Token.
client_id Required Use the Client ID assigned to the application.
client_secret Required Use the Client Secret from your Application (see details in Appendices).
redirect_uri Required Use the Redirect URI provided in the application's settings.

The client request for Access Token and Refresh Token is:

curl -w "\\n%{http_code}\\n" -X POST \
<authorization-token-endpoint> \
    -H 'Content-Type: application/json' \
    -d '{
    "grant_type":"refresh_token",
    "refresh_token":"<refresh_token>",
    "client_id":"<client_id>",
    "client_secret":"<client_secret>",
    "redirect_uri":"<redirect_url>"
}'
Please note the use of "grant_type":"refresh_token" to indicate this request is to issue a new Access Token and a new Refresh Token.

Example of request to get Access Token using Refresh Tokens:

curl -w "\\n%{http_code}\\n" -X POST \
https://identity-api.apps.us.bluescape.com/api/v1/oauth2/token \
    -H 'Content-Type: application/json' \
    -d '{
    "grant_type":"refresh_token",  
    "refresh_token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0eXBlIjoiUkVGUkVTSCIsImF1ZCI6WyI2YzQzNzIyM2UzYjA5NjJjMzFmMjllNzlmMGJmZGEyOWVhMWE2ODljIl0sInRva2VuIjoiQVlXMmR6TE9RZDZkdHExVFlsSFgwdHJReHg0RGVpaGJ3dGVlaG9MQmJ1UkJOeXhmMkIiLCJzdWIiOjE3ODcyLCJhenAiOiI2MzI2MzQzOSIsInNwaWQiOm51bGwsImFwcF9hdXRob3JpemF0aW9uX2lkIjoyNjcyLCJuYmYiOjE1NjU4MjI2NDAsImlhdCI6MTU2NTgyMjY1MCwiaXNzIjoiaHR0cHM6Ly9pZGVudGl0eS1hcGkudWF0MS5ibHVlc2NhcGUuY29tIn0.u13lw8kbQkHSYD5W_RP68z5zfsGcA2b_8Ofy9VdCSWs",
    "client_id":"60261A3D",
    "client_secret":"50bccef3a05f5433624ge8eb47a01c5d",
    "redirect_uri":"http://localhost/callback"
}'

The answer to this client request will be this:

{"access_token":"<access-token>","refresh_token":"<refresh-token>","expires_at":<expire-timestamp>,"token_type":"Bearer"}
Example:
{"access_token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0eXBlIjoiVVNFUiIsInN1YiI6MTc4NzIsInNwaWQiOm51bGwsImF1ZCI6WyIwMTVmNDgxYWNmZTQwMmM5YmFlNDM1Mzg5ZWZiYjY5MTQ5MjliZjhjIiwiNmM0MzcyMjNlM2IwOTYyYzMxZjI5ZTc5ZjBiZmRhMjllYTFhNjg5YyIsIjM2ZjhjZjUxNzVlNGZhYWE0ZjA2NzE4NDA0YjdkZjk0ZGRjMGQ4YWUiLCIwMTVmNDgxYWNmZTQwMmM5YmFlNDM1Mzg5ZWZiYjY5MTQ5MjljZTlkIl0sImV4cCI6MTU2NzAzMjM4NywiYXpwIjoiNjMyNjM0MzkiLCJsY04wZXMiOlsidXNlciJdLCJhcHBfYXV0aG9yaXphdGlvbl0pZDI6MjY3MiwibmJmIjoxNTY1ODIyNzc3LCJpYXQiOjE1NjU4MjI3ODcsImlzcyI6Imh0dHAzOi8vaWRlbnRpdHktYXBpLnVhdDEuYmx1ZXNjYXBlLmNvbSJ9.n82UABCIW3mVC1KFRyXrs2Hp1jkOVMTueiJOe9NOAcw","refresh_token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCK1.eyJ0eXBlIjoiUkVGUkVTSCIsImF1ZCI6WyI2YzQzNzIyM2UzYjA5NjJjMzFmMjllNzlmMGJmZGEyOWVhMWE2ODljIl0sInRva2VuIjoiaEduQTRiS0h4bV8tVlBxV2JxcmNYdmxWdFpzSTJPVzhNc0VQak5aS0o2aW9LZlZMQjUiLCJzdWIiOjE3ODcyLCJheyAiOiI2MzI2MzQzOSIsInNwaWQiOm51bGwsImFwcF9hdXRob3JpemF0aW9uX2lkIjoyNjciLCJuYmYiOjE1NjU4MjI3NzcsImlhdCI6MTU2NTgyMjc4NywiaXNzIjoiaHR0cHM6Ly9pZGVOdGl0eS1hcGkudWF0MS5ibHVlc2NhcGUuY29tIn0.tUwrE4-qiKiEVTHdpdgNMsqqmTHICDm3wcOj3FPCL64","expires_at":1567032387,"token_type":"Bearer"}

This request execution provides you with:

  1. access-token: this is the new Access Token you will use as the authentication to run your APIs, uses JWT format.
  2. refresh_token: this is the refresh token to use the next time you want to re-generate the Access Token.
  3. expire-timestamp: this is the expiration date of the Access Token, it is in Epoch format.

Next steps:

  • You can use this Access Token right away with your API scripts.
    1. Save this Access Token in a configuration file your scripts executing the APIs can read.
  • Use the Refresh Token to generate your new Access Token, this by verifying if the use of the current Access Token returns a 401 Unauthorized error code. If it does, then trigger an automated generation process usign the Refresh Tokens.

2.2.4. Troubleshooting

Error message Description and action to take
401 Unauthorized If, for any reason, the Access Token is not refreshed before its expiration date, you will get a 401 Unauthorized response from the Bluescape API. You will need to initiate this process flow again, from the generation of the Access Code, which required the user to login and Allow the application at Bluescape.
405 Not Allowed If you have not whitelisted the application, you will get an error message 405 Not Allowed. Please review the requirements outlined in Appendix 3.

Step 3: 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, this token grants add/modify/delete permissions to the APIs to anything the authenticated user has access to.
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 4: Using the Access Token

At this step you have your Access Token and you are ready to start using it. 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 eyJhbGciOiJIUzI1NiIsInR5cCI6pJ9.eyJpc...'

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

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

Please remember that 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, this according to the method you have chosen to manage your Access Tokens.

Full Example

Preconditions (example values)

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

Appendices

Appendix 1: Create a new Application

  • Go to developer.bluescape.com
  • Sign in: use Single Sign On login.
  • Go to top right link with your email address link, click it. In the drop down menu, click Applications
  • In the New window, click “New Application” button
  • Fill out the field fields:
    • Set the value for Whitelist Domains and Redirect URI the same. This is the redirect URL you will use when generating the tokens
    • Save
  • The new application is created:
  • The main data points you will need from here are the Client ID and Client Secret
    • It is critical that you maintain the Client Secret secret. You can always get a new Client Secret by clicking the Regenerate button. This operation will void the previously used Client Secret, so you need to update the new Client Secret in any place where it is being used.

Appendix 2: How to get the Client Secret

How to get the Client Secret:
  • Go to the Developer Portal website and log in
  • Go to top right link with your email address link, click it. In the drop down menu, click Applications
  • In the new window you get a list of Applications. Click the link with the name of the application you are using for this Token method
  • From here you can get:
    • client_id: value of Client ID
    • client_secret: value of Client Secret after clicking the Show button

Appendix 3: Requirements for Refresh Tokens implementation

You need to whitelist the application you will use to generate the tokens.

An ADMIN user from your organization needs to run this one time process:
  • Request:
    https://api.apps.us.bluescape.com/authorize?response_type=code&client_id=<app_id_to_whitelist>&redirect_uri=<redirect_uri>&org_id=<organization_id>&scope=org
  • Example:
    https://api.apps.us.bluescape.com/authorize?response_type=code&client_id=4563bA3&redirect_uri=https://developer.bluescape.com/tools/access-token/callback&org_id=4&scope=org
  • You will need to login and authorize the application, using the credentials of an ADMIN user for the organization specified in the URL
  • You will get back an Access Code you can use to generate the Access Code and Refresh Token.

How to obtain the Organization ID:
  • Go to Bluescape, log in as the user that created the application.
  • Click the user icon on the left column:
  • Inspect the URL in the browser: it contains the organization ID. example: https://portal.apps.us.bluescape.com/organizations/4/users, where “4” is the organization ID

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