API Application Authorization

Tom_Garrett · July 26, 2022, 6:44pm

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

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:

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.

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:

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

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:

Use response_type=code as the response_type.
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:

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

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

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:

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

Go to your application list: Applications
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: Applications
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.

image596×505 20.9 KB
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

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?

Basic API Requests

Bluescape API Guides

Bluescape API Overview

Latest Developer topics

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

Topic		Replies	Views
V3 API Application Authorization (with PKCE) Developer api	0	670	June 2, 2023
API Reference Tips and Tricks v3 Developer api	0	778	September 30, 2022
Application Registration information Developer api	0	1094	July 26, 2022
Migrating existing v2 API application to v3 OAuth2 Developer api	1	620	May 17, 2023
Bluescape API - Getting Started Guide Developer api	0	2096	July 26, 2022

API Application Authorization

OAuth Flow

Step 1: Direct the User to Bluescape for Authorization

Step 2: Choose how to manage your Access Token generation

2.1. Access Token generated manually

2.2. Access Token generated using Access Code and Refresh Token

2.2.1. Generate Access Code

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

2.2.3. Generate Access Token using Refresh Token

2.3 Troubleshooting

Step 3: Implement Code that Extracts the Access Token

Step 4: Using the Access Token

Full Example

Appendices

Appendix 1: Create a new Application

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

Appendix 3: Requirements for Refresh Tokens implementation

Where to Next?

Related topics