OAuth

OAuth enables external applications to grant access to resources in Yggio in a secure way.

Yggio supports OAuth2. It uses Authorization Code as authorization flow, which require your application to have a backend.

Before you can use OAuth you must create a provider via the Yggio REST API. It is important that you save the secret that is created for use in your application backend. There is no way of getting your secret back if you lose it, and the only solution then is to create a new provider.

Feel free to take a look at yggio service example to see an example of a working implementation.

How to use Yggio's OAuth in your application

Below is a sequence diagram showing the OAuth process, followed by a detailed description of the steps.

1. Gather the clientId and redirectUri of the provider which you previously created and redirect to /oauth at the Yggio server. Like so:

[yggioFrontendUrl]/oauth?client_id=x&redirect_uri=y&response_type=code

---

2. The Yggio server will redirect the browser to a sign in page where the user can enter their username and password and login. This step is skipped if the user has recently logged in.

---

3. The Yggio server redirects to a page where the user can choose to allow or deny the application to access their account. When the user presses "Allow" the Yggio server will redirect to your application frontend with redirectUrl together with a generated code. Like so:

[redirectUrl]?code=x&state=undefined

State is not used and can be ignored. If the user has previously pressed "Allow" this step is skipped.

---

4. At this page your application frontend should send a request to the backend, including the code.

---

5. The backend should then send a POST request to [yggioBackendUrl]/auth/oauth/token. This request should include the following in the body:

{'code': 'x', 'redirect_uri': 'y', 'grant_type': 'authorization_code'}

The request should also include an authorization header. Like so:

Authorization: Basic x

where x is 'clientId:secret' in Base64.

The Yggio server returns access_token, refresh_token and expiresAt.

---

6. Save the access_token, refresh_token and expiresAt in your application backend. The OAuth process is now finished. The access_token can then be used as an authorization header in future requests to the Yggio REST API. Like so:

Authorization: Bearer access_token

The refresh_token and expiresAt is used for refreshing the access token. See the following section.

Refreshing the access token

The access token is only valid for 30 days. To avoid demanding the user to login again, you can refresh the user's access token.

To refresh the access token the application sends the same request as the one in step 5, with the exception of the body instead containing the following:

{'grant_type': 'refresh_token', 'refresh_token': 'x'}

The response body is the same as in step 5.