Unmanaged (Plain HTTP) API Access with Authorization

Note: if you just need stats and don't need Scout user authorization (which is required for features like friends and verification) then follow this guide instead.

If our official SDKs are not an option for you and you need to develop your own method to access the Scout API, this guide will demonstrate the steps required in order to gain access and begin making requests.

Step 1: Authenticating with Scout

Scout uses industry standard security best practices for authorization with our API. This ensures Scout users' data is accessed securely and secures your application against potential threat actors as well. Scout uses the OpenID Connect 1.0 (OIDC) protocol for establishing a secure channel between your application and Scout. Because OIDC is a standard, it is likely that someone has developed a library already in your language of choice for communicating with it. You can find OIDC client implementations here.

Configuring OpenID Connect

Provided you're able to use OpenID Connect, you can use the following information to configure your client.

  • Scout's OIDC Discovery URL is https://api.scoutsdk.com (used for automatic configuration)
  • If your library doesn't support discovery, the OIDC configuration can be found here: https://api.scoutsdk.com/.well-known/openid-configuration
  • Client ID and secret can be found on your app details page.
  • You can test our OIDC implementation using this tool.

Support for OAuth 2.0 Libraries

If you aren't able to find an OpenID Connect client library, chances are you can find an OAuth 2.0 client library. OpenID Connect 1.0 is a superset of OAuth 2.0, which means it's backwards compatible with that standard.
Note: If you choose to use an OAuth 2.0 client library, please be aware that you must enable this option on your Scout app's settings page: look for "Enable OAuth 2.0 Compatibility"

The following settings should be used when configuring your application as an OAuth 2.0 client.

  • You must use the authorization code grant flow, implicit grant flow is not supported.
  • Authorization Endpoint: https://api.scoutsdk.com/connect/authorize
  • Token Endpoint: https://api.scoutsdk.com/connect/token

Supported Scopes

A full list of supported scopes is available in Scout's OIDC configuration. Refer to the scopes_supported property.

Step 2: Proving Authorization at Request Time

When you send an HTTP request to Scout, you must prove that your application has permission to access the resources it's requesting. To do this, your application needs to provide two headers to Scout.

Authorization header

The value of this header should be Bearer YOUR_ACCESS_TOKEN_HERE. Don't forget to include the "Bearer" part, it's important!

Scout-App header

Set your Scout client ID as the value of this header.

Step 3: Using the Graph

Scout uses Facebook's GraphQL protocol to retrieve information from our data services. This allows you to create queries for exactly the data you need. You'll find examples of GraphQL queries throughout the Scout documentation. If you want somewhere to test your queries, or learn more about the data Scout makes available, we encourage you to try our Graph Explorer. Below is an example of how to query the graph as plain old HTTP.

Note: The Accept header below is important. You must provide it exactly as it appears below.

  • HTTP