• The key and secret generated from an OAuth 2.0 configuration in OneRoster settings.
• Optional: Download and install Postman.

Requests to OneRoster 2.0 API endpoints require obtaining an access bearer token from the SKY API authorization /token endpoint.

An example request to the SKY API authorization /token endpoint:

POST /token HTTP/1.1
Host: https://oauth2.sky.blackbaud.com
Authorization: Basic base64EncodedKey:Secret
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&scope=scopename

POST /token HTTP/1.1
Host: https://oauth2.sky.blackbaud.com
Authorization: Basic base64EncodedKey:Secret
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&scope=scopename

Encode the key and secret

Encode the key and secret from OneRoster settings to Base64 format and include the encoded string as part of the Authorization header in the POST request to the SKY API /token endpoint.

Use the following commands to locally encode the key and secret to Base64 format from a command-line interface:

Windows (Powershell):

[Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes('key:secret'))

[Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes('key:secret'))

Mac OS & Linux (Terminal)

echo -n 'key:secret' | base64

echo -n 'key:secret' | base64

Using Curl

1. Open PowerShell (Windows) or Terminal (Mac, Linux).
2. Copy the following Curl command into PowerShell or Terminal, replacing base64EncodedKey:Secret with the Base64 encoded equivalent of key : secret obtained from OneRoster settings.
Copy

    curl \
    -X POST \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -H "Authorization:Basic base64EncodedKey:Secret" \
    -d "grant_type=client_credentials&scope=https://purl.imsglobal.org/spec/or/v1p1/scope/roster-core.readonly" \
    https://oauth2.sky.blackbaud.com/token
  

curl \
-X POST \
-H "Content-Type: application/x-www-form-urlencoded" \
-H "Authorization:Basic base64EncodedKey:Secret" \
-d "grant_type=client_credentials&scope=https://purl.imsglobal.org/spec/or/v1p1/scope/roster-core.readonly" \
https://oauth2.sky.blackbaud.com/token

3. The value of access_token is your access bearer token.

Using Postman

1. Select File > New.
2. Create a new Collection.
3. Under Authorization, set the Type to OAuth 2.0.
4. Enter a Token Name.
5. Set the Grant Type to Client credentials.
6. Enter the following as the Access Token URL:
https://oauth2.sky.blackbaud.com/token
7. Enter the key from an OAuth 2.0 configuration in OneRoster settings.
8. Enter the secret from an OAuth 2.0 configuration in OneRoster settings.
9. Select Get New Access Token.
10. Select Proceed.
11. The value of Access token is your access bearer token.

Requests to the /token endpoint require a scope included in the request. IMS Global defined these scopes as part of the OneRoster v1.1 specification; your bearer token can only grant access to specific endpoints and operations depending on which scopes you include when requesting the bearer token.

School API currently supports the following scopes and their corresponding endpoints:

Access tokens expire after 3600 seconds (i.e., one hour); applications must request a replacement token when the current one expires.