OAuth

If you are new to OAuth 2.0, the OAuth 2.0 Guide is a good place to start and learn some of the theory.

Following is an example of what the user experience might look like in your product:

Auth Steps

All applications follow a basic pattern when accessing a data.world API using OAuth 2.0. The flow can be slightly different, depending on whether the application web-based or native (desktop & mobile).

Web Application Flow

1. Application redirects user to https://auth.data.world/oauth/authorize for authorization, providing the following parameters:
   • client_id
   • redirect_uri
   • response_type = "code"
   • state

Example Authorization URL:

https://auth.data.world/oauth/authorize?
  client_id=3MVG9lKcPoNINVB&
  redirect_uri=http://localhost/oauth/code_callback&
  response_type=code

2. User logs into data.world and grants application access.

3. data.world redirects user back to the redirect_uri with:

   • code
   • state

4. Application takes the code and exchanges it for an access token:

   • client_id
   • client_secret
   • code
   • redirect_uri (optional)
   • grant_type = "authorization_code"

Example Token Request:

https://data.world/oauth/access_token?
  code=zac4ZV2XbleQ2e&
  client_id=3MVG9lKcPoNINVB&
  client_secret=3iQF9BsWEr6nCf&
  grant_type=authorization_code

5. If client_id and client_secret are valid data.world will respond with:
   • access_token
   • expires_in
   • refresh_token

Alternatively, if a redirect_uri was provided, data.world will invoke it passing the same list of attributes.

6. Application stores access_token to use in subsequent requests by placing it into the request as an Authorization: Bearer [access_token] header string.

❗️

This flow requires that your application runs on a web server

• Steps #3 and #4 can be performed while your client_secret remains protected behind a server environment.
• DO NOT include your client_secret for your web app in source code that accessible to others.
• Use the native applications flow instead, if you cannot guarantee the confidentiality of your client_secret.

Native Application Flow (desktop, mobile and static apps)

data.world supports the Proof Key for Code Exchange protocol to make the native application flow more secure.
A unique code verifier is created for every authorization request, and its transformed value, called code_challenge, is sent to the authorization server to obtain the authorization code.

Create the code verifier

A codeverifier is a high-entropy cryptographic random string using the unreserved characters `[A-Z] / [a-z] / [0-9] / "-" / "." / "" / "~"`, with a minimum length of 43 characters and a maximum length of 128 characters.
The code verifier should have enough entropy to make it impractical to guess the value.

Create the code challenge

Two methods of creating the code challenge are supported.

• plain: The code challenge is the same value as the code verifier generated above (code_challenge = code_verifier).
• S256: The code challenge is the Base64URL (with no padding) encoded SHA256 hash of the code verifier (code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))).

Once the values for code_verifier, code_challenge and code_challenge_method are defined, the flow proceeds, as follows:

1. Application redirects user to https://auth.data.world/oauth/authorize for authorization, providing the following parameters:
   • client_id
   • redirect_uri
   • response_type = "code"
   • state
   • code_challenge_method = "S256" or "plain"
   • code_challenge

Example Authorization URL:

https://auth.data.world/oauth/authorize?
  client_id=3MVG9lKcPoNINVB&
  redirect_uri=http://localhost/oauth/code_callback&
  response_type=code&
  code_challenge_method=plain&
  code_challenge=kBPZPENCUAfHyZRoGicqwhuzDawVgtpLsUpfJEvQgGbg6iEHqiteoDjrtgaErwEJ

2. User logs into data.world and grants application access.

3. data.world redirects user back to the redirect_uri with:

   • code
   • state

4. Application takes the code and exchanges it for an access token:

   • client_id
   • client_secret
   • code
   • redirect_uri (optional)
   • grant_type = "authorization_code"
   • code_verifier

Example Token Request:

https://auth.data.world/oauth/access_token?
  code=zac4ZV2XbleQ2e&
  client_id=3MVG9lKcPoNINVB&
  client_secret=3iQF9BsWEr6nCf&
  grant_type=authorization_code&
  code_verifier=kBPZPENCUAfHyZRoGicqwhuzDawVgtpLsUpfJEvQgGbg6iEHqiteoDjrtgaErwEJ

5. If client_id and client_secret are valid data.world will respond with:
   • access_token
   • expires_in
   • refresh_token

Alternatively, if a redirect_uri was provided, data.world will invoke it passing the same list of attributes.

6. Application stores access_token to use in subsequent requests by placing it into the request as an Authorization: Bearer [access_token] header string.

Reference implementation

Check out our reference implementation on GitHub.
This example, written in Node.js can be deployed to your Heroku account as-is with click of a button. Super easy!
Look for the Deploy to Heroku button at the bottom of the README.md.