API Application Authorization

Developer
1

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 the 401 Unauthorized returned response from the Bluescape API by initiating this flow again.

image
image746×1044 38.8 KB

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 in your user profile page under My Applications. After you sign in, go to the Applications option in the left list. Here you will be able to create and generate new client_ids for your applications (see Appendix 1). Use the value in the Client ID field as your client_id for this authentication process. See the reference in the image below.

image

When users arrive at 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 grants access to anyone who holds it to make calls on the behalf of the user who the name of the application is under.

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. Lasts 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 user to Allow the application in Bluescape. Requires a one-time task for user to login and authorize the generation of the Access Code. Can be automated. Requires the use of Access Code, client ID and client secret.

2.1. Access Token generated manually

This is the Oauth2 Implicit method. The workflow of this option is presented in this image:

image
image1228×1308 72 KB

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.

IMPORTANT: Note that with the new changes in Application Registration, the newly generate Applications will generate a longer ID. Difference in Applications IDs:

  • Previous Application ID (example): 60261A3D
  • Newest Application ID (example): 70304a04-d522-45fe-8f8e-cb238845a9af

Both Application ID formats will work for generating Access Tokens.

Example, replace client_id with your Client ID (application ID) and redirect_url with the redirect URL you configured in your Application (copy and paste them):

https://api.apps.us.bluescape.com/authorize?response_type=token&client_id=<client_id>&redirect_uri=<redirect_url>

For example (these are just illustration values):

https://api.apps.us.bluescape.com/authorize?response_type=code&client_id=70304a04-d522-45fe-8f8e-cba38845a9af&redirect_uri=https://127.0.0.1/callback

After the login and authorization of the application, you will be greeted with an error page in the browser; this is because you will have been redirected to a new URL, which will contain your token. Look at the the address bar of your browser (where you see your URL) to find your Token. This is an example of the expected return URL that contains the Token:

https://api.apps.us.bluescape.com/tools/access-token/callback#access_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0eXBlDCCCVNFUiIsInN1YiI6Mzg5ODgsImF1ZCI6WyIwMTVmNDgxYWNmZTQwMmM5YmFlNDM1Mzg5ZWZiYjY5MTQ5MjliZjhjIiwiNmM0MzcyMjNlM2IwOTYyYzMxZjI5ZTc5ZjBiZmRhMjllYTFhNjg5YyIsIjM2ZjhjZjUxNzVlNGZhYWE0ZjA2NzE4NDA0YjdkZjk0ZGRjMGQ4YWUiLCIwMTVmNDgxYWNmZTQwMmM5YmFlNDM1Mzg5ZWZ1YjY5MTQ5MjljZTlkIl0sImV4cCI6MTU2NzAyNzE5NiwiYXpwIjoiODlhY2NlODIiLCJzY29wZXMiOl3idXNlciJdLCJhcHBfYXV0aG9yaXphdGlvbl9pZCI6MjA1MSwibmJmIPoxNTY1ODE3NTg8LCJpYXQiOjE1NjU4MTc1OTYsImlzcyI6Imh0dHBzOi8vaWRlbnRp4XktYXBpLmFwcHMudOMuYmx1ZXNjYXBlLmNvbSJ9.5N1SpTv1FmxzhQujEY5kqjzJBTrWWnts2r9ilbm9Jis&token_type=Bearer

From this URL, you need to retrieve the access_token value. This is your Token:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0eXBlDCCCVNFUiIsInN1YiI6Mzg5ODgsImF1ZCI6WyIwMTVmNDgxYWNmZTQwMmM5YmFlNDM1Mzg5ZWZiYjY5MTQ5MjliZjhjIiwiNmM0MzcyMjNlM2IwOTYyYzMxZjI5ZTc5ZjBiZmRhMjllYTFhNjg5YyIsIjM2ZjhjZjUxNzVlNGZhYWE0ZjA2NzE4NDA0YjdkZjk0ZGRjMGQ4YWUiLCIwMTVmNDgxYWNmZTQwMmM5YmFlNDM1Mzg5ZWZ1YjY5MTQ5MjljZTlkIl0sImV4cCI6MTU2NzAyNzE5NiwiYXpwIjoiODlhY2NlODIiLCJzY29wZXMiOl3idXNlciJdLCJhcHBfYXV0aG9yaXphdGlvbl9pZCI6MjA1MSwibmJmIPoxNTY1ODE3NTg8LCJpYXQiOjE1NjU4MTc1OTYsImlzcyI6Imh0dHBzOi8vaWRlbnRp4XktYXBpLmFwcHMudOMuYmx1ZXNjYXBlLmNvbSJ9.5N1SpTv1FmxzhQujEY5kqjzJBTrWWnts2r9ilbm9Jis

2.2. Access Token generated using Access Code and Refresh Token

This is the Oauth2 Explicit method. The workflow of this option is in the image below:

image
image1329×1869 125 KB

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, you first need to generate an Access Code. In this first step, if Authenticating with Bluescape, do the following:

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

Replace client_id with your Client ID and redirect_url with the redirect URL you configured in your Application (copy and paste them):

https://api.apps.us.bluescape.com/authorize?response_type=code&client_id=<client_id>&redirect_uri=<redirect_url>

For example (these are just illustration values):

https://api.apps.us.bluescape.com/authorize?response_type=code&client_id=70304a04-d522-45fe-8f8e-cba38845a9af&redirect_uri=https://127.0.0.1/callback

After the login and authorization of the application, you will be redirected to a new URL and greeted with an error page in the browser. The address bar (where you see your URL) contains the Access Code. Example:

https://api.apps.us.bluescape.com/tools/access-token/callback?code=BFyQPkmEYeSmWP1XYmeiXRJtdEgJLY

Here is the Access Code: 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 allow for 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-api.apps.us.bluescape.com/api/v2/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 (Step 2.2.1).
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 "%{http_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>"
}'

IMPORTANT: Note that with the new changes in Application Registration, the newly generate Applications will generate a longer ID. Difference in Applications IDs:

  • Previous Application ID (example): 60261A3D
  • Newest Application ID (example): 70304a04-d522-45fe-8f8e-cb238845a9af

Both Application ID formats will work for generating Access Tokens.

Example of the request:

curl -w "%{http_code}\\n" -X POST \
https://identity-api.apps.us.bluescape.com/api/v2/oauth2/token \
    -H 'Content-Type: application/json' \
    -d '{
    "grant_type":"authorization_code",
    "code":"AIT6zDsPGaB-46T2mHlU0DJ-kh-Vuz",
    "client_id":"70304a04-d522-45fe-8f8e-cb238845a9af",
    "client_secret":"50bccef3a05f5433624ge8eb47a01c5d",
    "redirect_uri":"http://127.0.0.1/callback"
}'

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

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

{"access_token":"<YOUR-ACCESS-TOKEN-VALUE>","refresh_token":"<YOUR-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; it 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.
  • Refresh Tokens do not expire. This means you can generate your new Access Tokens using the Refresh Tokens at any moment, before or after the current Access Token expires.
  • If an Access Token is used after it has expired, you will get a ‘401 Unauthorized’ error code. In this case you will need to trigger the process to generate a new Access Token using the Refresh Token (as explained in the next section)

2.2.3. Generate Access Token using Refresh Token

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

  1. To see if your Access token is still valid, you can either check its expiration time, or simply try using it in any valid Bluescape API call.
  2. If you get a 401 Unauthorized error code, then you can 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-api.apps.us.bluescape.com/api/v2/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 Appendix 2).
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 "%{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>"
}'

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 "%{http_code}\\n" -X POST \
    https://identity-api.apps.us.bluescape.com/api/v2/oauth2/token \
        -H 'Content-Type: application/json' \
        -d '{
        "grant_type":"refresh_token",  
        "refresh_token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0eXBlIjoiUkVGUkVTSCIsImF1ZCI6WyI2YzQzNzIyM2UzYjA5NjJjMzFmMjllNzlmMGJmZGEyOWVhMWE2ODljIl0sInRva2VuIjoiQVlXMmR6TE9RZDZkdHExVFlsSFgwdHJReHg0RGVpaGJ3dGVlaG9MQmJ1UkJOeXhmMkIiLCJzdWIiOjE3ODcyLCJhenAiOiI2MzI2MzQzOSIsInNwaWQiOm51bGwsImFwcF9hdXRob3JpemF0aW9uX2lkIjoyNjcyLCJuYmYiOjE1NjU4MjI2NDAsImlhdCI6MTU2NTgyMjY1MCwiaXNzIjoiaHR0cHM6Ly9pZGVudGl0eS1hcGkudWF0MS5ibHVlc2NhcGUuY29tIn0.u13lw8kbQkHSYD5W_RP68z5zfsGcA2b_8Ofy9VdCSWs",
        "client_id":"70304a04-d522-45fe-8f8e-cb238845a9af",
        "client_secret":"50bccef3a05f5433624ge8eb47a01c5d",
        "redirect_uri":"http://127.0.0.1/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; it 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 that your scripts executing the APIs can read.
  • Use the Refresh Token to generate your new Access Token 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 using the Refresh Token.

2.3 Troubleshooting

If you get an error message when trying to authenticate and authorize, or when trying to generate your Tokens, please review the error messages and error codes in the table below.

If you get an error message when trying to authenticate and authorize, or when trying to generate your Tokens, please review the error messages and error codes in the table below.

Error message Description and action to take
“Oops, something went wrong” If you see this message in the step to authenticate and authorize in order to generate an Access Token or an Access Code, please verify that the Redirect URL you set in your Developer Portal Application is the same one you are using as the redirect_uri parameter in the URL you are using to generate the Access Token or Access Code.
For example, let’s consider this Application:

image
image596×505 20.9 KB

For the image above, the correct value for redirect_uri is http://127.0.0.1/callback, and the full URL to trigger the Access Token generation would be:

https://api.apps.us.bluescape.com/authorize?response_type=token&client_id=9076e5d4-6a83-4233-a826-c1ec547c8a44&redirect_uri=http://127.0.0.1/callback

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.
If you are using manual generation of the Access Token, then you need to manually generate a new Access Token.
If you are using the Access Code with Refresh Tokens approach, you will need to trigger a process to use the Refresh Token to generate a new Access Token and a new Refresh Token.
405 Not Allowed If you have not Allowed 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. You should store it safely because this token grants add/modify/delete permissions to any of the APIs the authenticated user has access to.
token_type Always has value Bearer.

Step 4: Using the Access Token

At this point, 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 });

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

Full Example

IMPORTANT: Please note that with the new changes in Application Registration, the newly generated Applications will generate a longer ID. Difference in Applications IDs:

  • Previous Application ID (example): 60261A3D
  • Newest Application ID (example): 70304a04-d522-45fe-8f8e-cb238845a9af

Both Application ID formats will work for generating Access Tokens.

Preconditions (example values)

Name Value
Application Name My Bluescape App
Application Redirect URI https://my-bluescape-app.io/oauth/callback
Application Client ID 70304a04-d522-45fe-8f8e-cb238845a9af
Application Allowed Domains https://my-bluescape-app.io

Authorization URL

https://api.apps.us.bluescape.com/authorize?response_type=token&client_id=70304a04-d522-45fe-8f8e-cb238845a9af&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

  1. Go to your application list: Applications
  2. Sign in, if you haven’t already.
  3. In the left menu, select “Applications”

image

  1. Click the “New Application” button
  2. Fill out the required fields:
    • Oauth redirect uri: after the initial process to generate the Access Token or Access Code is run, it will use this URL to redirect the workflow to deliver (depending on the Oauth method) the Access Token or Access Token and Refresh Token. For manual generation of the Access Token, you can set it as http://127.0.0.1/callback

image

  1. Save

  2. The new application is created:
    image

  3. The main data points you will need from here are the Client ID and Client Secret. See Appendix 2 for retrieving the Client ID and Client Secret.

Appendix 2: How to get the Client ID and Client Secret

How to get the Client Secret:

  1. Go to your application list: Applications

  2. Sign in, if you haven’t already.

  3. In the left menu, select “Applications”
    image

  4. To view the Client Secret, click the gear gear to the right of the application, then, the eye eye icon.

  5. This will display your client secret.

  6. It is critical that you keep the Client Secret a secret. You can always get a new Client Secret by clicking the Regenerate regenerate button. This operation will void the previously used Client Secret, so you will need to update the new Client Secret in any place where it is being used.

    image
    image596×505 20.9 KB

  7. From here you can get:

  • client_id: value of Client ID
  • client_secret: value of Client Secret after clicking the Show button after clicking the eye eye icon .

Appendix 3: Requirements for Refresh Tokens implementation

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

IMPORTANT: Please note that with the new changes in Application Registration, the newly generate Applications will generate a longer ID. Difference in Applications IDs:

  • Previous Application ID (example): 60261A3D
  • Newest Application ID (example): 70304a04-d522-45fe-8f8e-cb238845a9af

Both Application ID formats will work for generating Access 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_allow>&redirect_uri=<redirect_url>

where <redirect_url> is the redirect URL set in the configuration of the application.

  • Example:

https://api.apps.us.bluescape.com/authorize?response_type=code&client_id=70304a04-d522-45fe-8f8e-cb238845a9af&redirect_uri=https://api.apps.us.bluescape.com/tools/access-token/callback

  • 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.

Where to Next?

Not what you were looking for? Reply below or Search the community and discover more Bluescape.