SceneID

How SceneID / OAuth2.0 works

SceneID is based on the OAuth 2.0 authorization protocol; since OAuth itself is widely used and documented, we won't go into the deep nitty-gritty of the protocol itself, but we'll run through a quick checklist of things you should know.

The event flow

When a user signs in to your website via SceneID, here's the sequence of events that will happen:

  1. The user clicks on the login link on your site.
  2. Your site forwards the user to the SceneID authorization page, while providing the credentials for your site in the URL.
  3. The user, if not logged in to SceneID, receives a login form where they can provide their SceneID account info.
  4. The user, if they haven't logged in to your site before just yet, receives a prompt that they must explicitly authorize your site to access their data.
  5. Once the user has confirmed the authorization, SceneID forwards the user back to your website with various opaque credentials.
  6. Using these opaque, temporary credentials, your site establishes communication with SceneID.
  7. SceneID identifies the credentials, and provides your site with an access token.
  8. Using this access token, your website can now access the user's SceneID resources.

During this process, your site has no contact with the user's username or password, and the user can revoke your access to their information at any point.

API keys

To access SceneID, your website is going to need an API key, which is a client ID and a client secret. You can obtain an API key by contacting us: tell us about your site, what you'd use SceneID for, and what your redirect URI would be (see below), and we'll provide you with the required credentials after you've set up.

Endpoints

There are currently 3 endpoints for the OAuth 2.0 server:

  • https://id.scene.org/oauth/authorize/ is the authorization endpoint: forward the user here with the correct query string to start the authorization process.
  • https://id.scene.org/oauth/token/ is the token endpoint. Once you've authorized the user, you can access this endpoint to get your access and refresh tokens.
  • https://id.scene.org/oauth/tokeninfo/ is a token information endpoint for added security; you can verify your access token's credentials here.

Step 1: Authorization

The first step in logging a user in is always sending them to the SceneID authorization page. This is recommended to be done by redirecting them once they clicked a button - while it is possible to generate the authorization page URL, and create a direct clickable link for the user, it is generally not recommended for security reasons.

The authorization URL should look like the following:

https://id.scene.org/oauth/authorize/?client_id=[...]&redirect_uri=[...]&response_type=code&state=[...]

This lets SceneID know where the user is coming from, and establishes a one-time session.

  • client_id is your client ID provided by us once you've applied to an API key.
  • redirect_uri is a page on your website the user will arrive back to once they've entered their password - this page will do the actual authentication. Because this is critical to the security of the process, you need to provide all valid redirect URIs to us when you request the API keys.
  • state must be a random string to identify this current session. Make sure to store this string in the user's session until the end of the entire process.
  • response_type is currently only allowed to be "code".

From a user interface perspective, it's best practice to clearly indicate that the user can and will use SceneID for authenticating with your site. To this end, you can use a variety of pre-made login button images we'll provide here:

  • button
  • button

You can download more shapes and sizes (including vector versions) of the buttons here.

Step 1.a: Scopes

Depending on how much information your site requires, you may add a set of scopes to your initial request. This allows you to finetune what the user allows you to see or not see from their data.

Adding scopes is simply done by modifying the above authorization URL like so:

https://id.scene.org/oauth/authorize/?client_id=[...]&redirect_uri=[...]&response_type=code&state=[...]&scope=[...]

Where scope is a space-delimited list of the scope strings you wish to access.

SceneID currently supports the following scopes:

  • basic provides the basic information such as display name and real name. This scope is default when no scope is provided.
  • user:email provides the user's email address in the /me request.

Step 2: Token retrieval

Once the user has provided their credentials and authorized your site, they will be redirected to the URL you have provided, with a one-time response code or authorization code.

The URL the user lands on will look like the following:

https://my.domain.tld/my-return-path/?code=[...]&state=[...]

  • code is the one-time authorization code.
  • state should be the same random string you provided (and stored) in Step 1. If it's not, it is recommended that you abort the entire authorization process.

Using code you can now request an access token.

Step 2.a: Accessing the token endpoint

Accessing the token endpoint must be done through basic HTTP authentication, using your client ID as username and your client secret as password:

This means if your client ID is "test" and client secret is "test1234", you must provide the following header when accessing the token endpoint:

Authorization: Basic dGVzdDp0ZXN0MTIzNA==

... where dGVzdDp0ZXN0MTIzNA== is test:test1234 encoded with Base64.

Step 2.b: Accessing the token endpoint

To get an access token, send a standard HTTP POST request to https://id.scene.org/oauth/token/ with the following POST contents: (don't forget the basic authentication!)

grant_type=authorization_code&code=[...]&redirect_uri=[...]

  • grant_type is always authorization_code.
  • code is the same authorization code you've been sent in the query string.
  • redirect_uri is the same redirect URI you've provided during authorization.

You will in return receive something like this

{"access_token":"[...]","expires_in":"[...]","token_type":"[...]","scope":"[...]"}

From this, you will mostly need the access_token - this will allow you to access resources on SceneID. Important: Keep this token secure and not user-facing!

Step 3: Resource access

Finally, once you have the access token, you can access the resource in the endpoint URL below.

To authenticate with the resource endpoint, you must provide the following HTTP request header:

Authorization: Bearer [...]

...where [...] is your access token.

"Anonymous" access: client credentials

For certain parts of the API, user credentials aren't necessary. For this, you can apply for client credentials by sending the following request to the token endpoint: (remember the basic authentication!)

grant_type=client_credentials

The steps after this are identical to the remainder of Step 2.b.

Restrictions

There are a few OAuth2-related restrictions that are to be considered when logging in:

  • The "user credentials" grant-type is currently not supported.
  • The only response type supported is authorization code.

This currently makes it complicated to use SceneID for desktop client purposes. With further iterations of the service, we will work on making this easier.

Commands

Once you've authenticated with OAuth 2.0, you may perform commands; the endpoint for the actual API is at https://id.scene.org/api/3.0/[command]/ where [command] is obviously the command you want to use.

Common properties

  • All outgoing data is UTF-8, all incoming data is treated as UTF-8.
  • You may request the data in various formats by providing the format=... query parameter. Valid values are json and xml - default is json.

/me/

Returns the user data for the currently logged in user.

Required credentials
User
Parameters
None
Returns
A user object pertaining to the user whose access token we're using. If the user:email scope is supplied, it also includes an email member.
Example request
https://id.scene.org/api/3.0/me/
Example response
{"success":true,"user":{"id":"1","first_name":"John","last_name":"Doe","display_name":"JD ^ MegaCrew"}}

/user/

Returns the user data for any user.

Required credentials
User or client
Parameters
  • id: The desired user ID (required)
Returns
A user object pertaining to that certain user ID. If the user object contains a key called legacy and it is set to true, then the user hasn't migrated their account yet.
Example request
https://id.scene.org/api/3.0/user/?id=1
Example response
{"success":true,"user":{"id":"1","first_name":"John","last_name":"Doe","display_name":"JD ^ MegaCrew"}}

Integration tips

  • You may use the user ID as the primary identity; display name may change over time and should not be relied on.
  • If your website already has a working username / password login system, and you wish to integrate SceneID as an easier way of logging in, it is recommended to allow the user to connect his existing account. Possibly the best way of doing this is authenticating the user, and then looking up their SceneID in your user table. If the user has no account associated yet, offer them to either connect an old one or create a new one before letting them access the rest of the site.
  • If not necessary, don't query user information. Caching it in your own database is a lot more efficient.

SDKs

We'll continue to provide you with pre-written libraries to ease the integration of SceneID into your site:

For other helper libraries, take a look at the official OAuth 2.0 website.