Application Authorization
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.
Content in this page:
- OAuth Flow
- Step 1: Authorize
- Step 2: Choose how to generate the Access Tokens:
- 2.1 Access Token generated manually or 2.2 Access Token generated using Access Code and Refresh Tokens
- 2.3 Troubleshooting
- Step 3: Extract the Access Tokens
- Step 4: Using the Access Token
- Appendices
- 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.
- 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.
- If user authentication is successful, Bluescape redirects the user back to the application along with a newly generated access token.
- The application extracts the access token and is then able to start querying the Bluescape API.
- 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.

Step 1: Direct the User to Bluescape for Authorization
Applications requesting an access token should direct users to the authorization page at:
/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 the page. 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.

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

To generate this Token, please:
- Use response_type=token as the response_type.
- Set your client_id into the example URL below and paste it into a browser.
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
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):
/authorize?response_type=token&client_id=<client_id>&redirect_uri=<redirect_url>For example (these are just illustration values):
/authorize?response_type=code&client_id=70304a04-d522-45fe-8f8e-cba38845a9af&redirect_uri=https://127.0.0.1/callbackAfter 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:
/tools/access-token/callback#access_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0eXBlDCCCVNFUiIsInN1YiI6Mzg5ODgsImF1ZCI6WyIwMTVmNDgxYWNmZTQwMmM5YmFlNDM1Mzg5ZWZiYjY5MTQ5MjliZjhjIiwiNmM0MzcyMjNlM2IwOTYyYzMxZjI5ZTc5ZjBiZmRhMjllYTFhNjg5YyIsIjM2ZjhjZjUxNzVlNGZhYWE0ZjA2NzE4NDA0YjdkZjk0ZGRjMGQ4YWUiLCIwMTVmNDgxYWNmZTQwMmM5YmFlNDM1Mzg5ZWZ1YjY5MTQ5MjljZTlkIl0sImV4cCI6MTU2NzAyNzE5NiwiYXpwIjoiODlhY2NlODIiLCJzY29wZXMiOl3idXNlciJdLCJhcHBfYXV0aG9yaXphdGlvbl9pZCI6MjA1MSwibmJmIPoxNTY1ODE3NTg8LCJpYXQiOjE1NjU4MTc1OTYsImlzcyI6Imh0dHBzOi8vaWRlbnRp4XktYXBpLmFwcHMudOMuYmx1ZXNjYXBlLmNvbSJ9.5N1SpTv1FmxzhQujEY5kqjzJBTrWWnts2r9ilbm9Jis&token_type=BearerFrom 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:

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.
Verify that you have met all the requirements outlined in Appendix 3, otherwise this process will not generate the Refresh Tokens correctly. |
To generate this Refresh Token, you first need to generate an Access Code. In this first step, if Authenticating with Bluescape, do the following:
A) Use response_type=code as the response_type.
b) 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):
/authorize?response_type=code&client_id=<client_id>&redirect_uri=<redirect_url>For example (these are just illustration values):
/authorize?response_type=code&client_id=70304a04-d522-45fe-8f8e-cba38845a9af&redirect_uri=https://127.0.0.1/callbackAfter 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:
/tools/access-token/callback?code=BFyQPkmEYeSmWP1XYmeiXRJtdEgJLYHere 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: /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: 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
Example of the request:
curl -w "%{http_code}\\n" -X POST \ /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. 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:
- access-token: this is the Access Token you will use as the authentication to run your APIs; it uses JWT format.
- refresh_token: this is the refresh token.
- 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:
- 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.
- 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: /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>" }'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 "%{http_code}\\n" -X POST \ /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:
- access-token: this is the new Access Token you will use as the authentication to run your APIs; it uses JWT format.
- refresh_token: this is the refresh token to use the next time you want to re-generate the Access Token.
- 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.
- 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.
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: ![]() 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: /authorize?response_type=token&client_id=9076e5d4-6a83-4233-a826-c1ec547c8a44&redirect_uri=http://127.0.0.1/callback |
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.
|
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=BearerSample 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 /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 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 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
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
/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
Appendix 1: Create a new Application
- Go to your application list:
- Sign in, if you haven't already.
- In the left menu, select "Applications"
- Click the “New Application” button
- 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
- Save
- The new application is created:
- 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:
- Go to your application list:
- Sign in, if you haven't already.
- In the left menu, select "Applications"
- To view the Client Secret, click the gear to the right of the application
Then, the eye icon
This will display your client secret.
- It is critical that you keep the Client Secret a 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 will need to update the new Client Secret in any place where it is being used.
- 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 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
An ADMIN user from your organization needs to run this one time process:
- Request:
/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:
/authorize?response_type=code&client_id=70304a04-d522-45fe-8f8e-cb238845a9af&redirect_uri=/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.
If you have any questions or comments, please contact us in the Bluescape Community site.