Application Scopes

Scopes

Scopes specify what rights an application has for data access. Each API endpoint has certain scope requirements. A user must have authorized these scopes for an application in order for the endpoint to respond with the data requested. If a required scope is missing, an API request will return a valid JSON object without the portion of data requiring that scope. If all required scopes are missing for an API request, it will return an empty JSON object.

There are application-level scope rights and token-level scope rights. Token-level scope rights are what determine whether the requested data will be returned. Token-level scopes are issued per auth token based on the parameters passed in a user’s OAuth flow. Requested token-level scopes may vary from one token to the next, though this is not common in practice.

App-level scope rights are given at the application level. They govern the maximum set of scopes allowed to a token to be granted during a user’s OAuth flow. A token cannot ask to have a scope unless it has the app-level rights for that scope. Adding an application level scope will not affect tokens issued beforehand: the tokens will still be valid and will not have any way to get the new scope. Removing an application-level scope will invalidate any tokens already issued which have the removed scope.

Some of the possible scopes are:

Scope Name Description
scope:public Access to public information about user.
scope:user:profile Access to user's profile (i.e. first_name, last_name, email).
scope:location Access to historical location. Applies to all events.
scope:current_location Access heartbeat location updates in real-time during a drive.
NOTE: this scope governs one very special event only, location:updated, and is only needed for a narrow class of apps. This event is only supported via websockets. Importantly, this scope is NOT needed for location information in trips or vehicle events.
scope:vehicle:profile Access to vehicle information (i.e. year, make, model). Applies to all events.
scope:vehicle:events Access to vehicle events details (i.e. hard_brake, hard_accel).
scope:vehicle:stream Access to vehicle streaming PIDs
scope:vehicle:vin Access to VIN (Vehicle Identification Number).
scope:trip Access to trips that are visible to a user.
NOTE: the Trip endpoint requires many scopes to get the complete set of data. scope:trip alone does not give very much, but is required to get anything in the Trip object.
scope:behavior Access to user's driving behavior summary stats.