OAuth Applications

You can use Blender ID as OAuth provider for your application. In order to do so:

Request (via mail to production at blender.org) Blender ID Application credentials by providing:
- The name of the Application
- The URL of the Application
- The return URL
- And image to be used in the OAuth screen
Define the scopes of the Application and use the API endpoints accordingly

The main benefits of using Blender ID for your Application are:

Use a service trusted within the Blender Community
Access to Blender ID badges associated to a user (Blender Development Fund Membership, Blender Studio subscriptions, etc.)

API endpoints

https://id.blender.org/oauth/authorize: Authorization endpoint
https://id.blender.org/oauth/token: OAuth token validation endpoint
https://id.blender.org/api/me: Retrieve info about the current user. Returns a JSON doc with the following keys:
- id: User ID (this will not change - use to create a reference to the user in your Application)
- full_name: User full name
- email: User email address
- nickname: User nickname
- roles: Dictionary with active public roles associated with the user
  - TODO: specify which roles are currently available
- date_deletion_requested: Date when user account deletion was requested, if ever
- confirmed_email_at: Date when email was confirmed, if ever
- avatar_url: URL of the avatar, if set
https://id.blender.org/api/user/<user_id>: Retrieve info about any user (requires userinfo scope)
https://id.blender.org/api/badges/<user_id>: Retrieve badges for the user (requires a matching token). Returns a JSON doc with the following keys:
- label: Human readable name
- link (optional): URL to a website relevant to the badge
- description (optional): Short description of the badge
- image (optional): URL to the badge image
- image_width (optional): Image width
- image_height (optional): Image height

This document describes the OAuth token scopes used by Blender ID.

These scopes are assigned to tokens owned by API users. These are generally not real flesh-and-blood users, but system accounts.

badger: Grants the owner of this token to assign and revoke roles. The set of allowed roles is determined by the roles of the owner (for example, the Blender Store system user has the cloud_badger, which allows assigning and revoking the cloud_has_subscription and cloud_subscriber roles). new users, and to check for user existence. This is used by Blender Store.
authenticate: Grants the possibility to check an email/password combination for validity. This is used by Blender Store.
userinfo: Grants the caller to access user info of arbitrary users. This is used by Blender Cloud.

These scopes are assigned to tokens owned by regular users of Blender ID.

email: The default scope for any token given to a user upon login. Grants access to the basic user information, such as email address, full name, and nickname.
badge: Grants the caller access to badge info (as JSON and HTML) of the user who owns the token.

In this example we use Blender Studio, for other applications using roles/badges setup will be similar.

To allow Blender Studio to call our API endpoints, do the following:

Add an OAuth2 application for the API, name it "Blender ID API". You can choose any name, but it's nice if we all use the same so we can recognise it. Set it to 'Confidential' and 'Resource owner password-based'.
Make sure that the cloud_demo and cloud_subscriber roles exist, and that they are badges. Add a role cloud_badger and allow it to manage the above roles.
Add a user for Blender Studio, for example using "yourname+studio@yourdomain.com" as email address. The password doesn't matter -- give it a long one and forget about it. Give the user the cloud_badger role.
Add an OAuth2 token to the Blender Studio user for the Blender ID API application. Make sure it doesn't expire any time soon (e.g. somewhere in the year 2999). Give it a scope badger.
Configure the Blender Studio to use this token to authenticate its API calls.