This is an overview of how OneGraph's auth flow works. If you're building applications in the browser, you can save yourself some work and use our auth.js library.

OneGraph handles service authentication for your app to make querying against e.g. Twitter or Google on your user's behalf much easier.

There are a few different kinds of authentication OneGraph offers, but we'll focus on in-browser authetication for now.

Let's first query some data to see if "me" (the current user) is logged into Twitter:

{
  me {
    twitter {
      screenName
      name
    }
  }
}

The response comes back:

{
  "data": {
    "me": {
      "twitter": null
    }
  }
}

Check out similar queries for other services OneGraph support, like GitHub, and Stripe!

Asking your user to sign in

With the above me query, now all we need to complete logging into a service like Twitter is to have OneGraph guide them through the OAuth flow.

The flow to authorize users for a service is:

Users are directed to OneGraph
OneGraph directs the user to the underlying service for authentication, then redirects them back to your site
Your app accesses their data with an access token that OneGraph provides

1. Users are directed to OneGraph

GET https://serve.onegraph.com/oauth/start

Query Parameters

Name	Type	Description
service	string	One of the services that OneGraph supports (eventil, github, gmail, google, google-compute, google-docs, salesforce, stripe, twilio, twitter, youtube, and zendesk as of July 2018)
app_id	string	Your app id (create an app on the Dashboard)
response_type	string	This value should always be `code`
state	string	An unguessable random string that is used to protect against cross-site request forgery
redirect_origin	string	The URL in your application where users will be sent. This should be listed as one of your CORS origins
redirect_path	string	Optional param that specifies the path of the url that users will be redirected to

Example url

https://serve.onegraph.com/oauth/start?service=gmail&app_id=${YOUR_APP_ID}&response_type=code&state=s123&redirect_origin=https://example.com&redirect_path=/foo

2. OneGraph redirects users back to your site

If your user gives access, OneGraph will redirect them back to your site with a temporary code in a code parameter, along with the state you provided in a state parameter. Make sure the state param matches the one you provided.

Exchange the code for an access token:

POST https://serve.onegraph.com/oauth/token

Query Parameters

Name	Type	Description
grant_type	string	This value should be `authorization_code`
service	string	One of the services that OneGraph supports (eventil, github, gmail, google, google-compute, google-docs, salesforce, stripe, twilio, twitter, youtube, and zendesk as of July 2018)
app_id	string	Your app id
redirect_uri	string	A combination of the redirect_origin and redirect_path you provided in the previous request
code	string	The code you received
expires_in	int	Optional param that specifies the number of seconds until the token should expire. Use this to help you test the refresh flow. Providing a value that is over two weeks of seconds will cause the request to be rejected. If you need long-lived tokens, go to the `Auth Services > Server-side` page of the dashboard.

If successful the response will be json-encoded with keys access_token and expires_in, the number of seconds until the token expires. It will also contain a refresh token you can use to generate a new access_token once your current token expires.

Example curl request

curl -X POST https://serve.onegraph.com/oauth/token?grant_type=authorization_code&service=gmail&app_id=$YOUR_APP_ID&redirect_uri=https://example.com/foo&code=c123

Reponse

{
  "access_token": "abcd123",
  "expires_in": 8600,
  "refresh_token": "efgh456"
}

If there is an error, the response will be json-encoded with a short error message under the error key, and a longer description under the error_message key:

{
  "error": "invalid_grant",
  "error_description": "code is expired"
}

Use the access token from the response to make requests to OneGraph using the Authentication header:

Authorization: Bearer YOUR_TOKEN

If the token is "abc123", the request will be:

curl -X POST 'https://serve.onegraph.com/graphql?app_id=0b33e830-7cde-4b90-ad7e-2a39c57c0e11' \
  -H "Authorization: Bearer abc123" \
  --data '{"query":"{ me { twitter { screenName } } }"}'

If you want to log in to multiple services, pass an existing access_token in the Authorization header when you exchange the code for an auth token. The auths for that token will be added to the token that is returned to you.

That's enough to get going! We'll handle security and safety, relying on the OneGraph's handling of the browser's built-in cookie and CORS mechanisms.

You may want to use some of the handy-dandy convenience npm packages that add features and polish (check out the front-end dev section further along), but that's OneGraph browser authentication at its core.

Now if we try the same query above (after logging in), the response looks like:

{
  "data": {
    "me": {
      "twitter": {
        "screenName": "onegraphio",
        "name": "OneGraph"
      }
    }
  }
}

Refreshing a token

Once your access token expires, you can get a new token with the refresh token you received when exchanging the code.

POST https://serve.onegraph.com/oauth/token

Query Parameters

Name	Type	Description
grant_type	string	This value should be `refresh_token`
app_id	string	The app id that created the token
refresh_token	string	The refresh token that you received with the original token
expires_in	int	Optional param that specifies the number of seconds until the token should expire. Use this to help you test the refresh flow. Providing a value that is over two weeks of seconds will cause the request to be rejected. If you need long-lived tokens, go to the `Auth Services > Server-side` page of the dashboard.

Example request

curl -X POST https://serve.onegraph.com/oauth/token?grant_type=refresh_token&app_id=${YOUR_APP_ID}&refresh_token=efgh456

Reponse

{
  "access_token": "ijkl789",
  "expires_in": 8600,
  "refresh_token": "mnop012"
}

You will get a new access_token and a new refresh_token. You can discard the refresh_token that you used and replace it with the refresh_token in the response.

Browser security

OneGraph strictly enforces a safe-list of CORS origins for your app. No request originating from an app outside of your safe list will have access to any of the service authentications your user has given your app.

Go check out your app in the OneGraph dashboard now and add http://localhost:3000 to the list of CORS origins allowed to get started building an app locally.

What's next?

Take a look at how to use OneGraph with your existing Apollo or Relay clients to get started, explore your queries in OneGraphiQL or get live help on our Spectrum channel for any questions and suggestions.