How authorization works

Yango Dialogs interacts with the skill and authorization server via OAuth 2.0 using authorization code grant.

When the user authenticates at the authorization server, the server sends the code to Yango Dialogs to get the token. Yango Dialogs use this code to request an OAuth token and a refresh token used for updating the access token when it expires.

Yango Dialogs send the OAuth token to the skill. The skill must use this token in its requests to your service to get private resources.

OAuth authorization and roles

OAuth 2.0 defines the following roles:

Resource owner: User.
Resource server: A smart device manufacturer's server that provides access to device data by access tokens.
Client: An application (skill) that sets up communication between the user and smart devices.
Authorization server: Verifies the authenticity of the data provided by the resource owner and issues authorization tokens. The client uses them to request access to the user's devices data.
The maximum response length is 5000 characters, and the maximum length of the OAuth token or refresh token is 2048 characters. The token lifetime (the expires_in property) must be an integer between 1 and 4,294,967,296.

The example of the Aqara app below shows how OAuth roles are used in skills.


Role in OAuth	Role in skills
Resource owner	The user who wants to allow the skill to access their data in the Aqara app.
Resource server	The Aqara app that stores the user's device info.
Client	Your skill that is used to set up communication between the user and the Aqara resource server.
Authorization server	This server does the following: Authenticates skill users. Requests confirmation for accessing data in the Aqara app. Generates a token. The token is passed to the skill, and the skill sends it in requests to Aqara.


Role in OAuth	Role in skills
Resource owner	The user who wants to allow the skill to access their data in the Aqara app.
Resource server	The Aqara app that stores the user's device info.
Client	Your skill that is used to set up communication between the user and the Aqara resource server.
Authorization server	This server does the following: Authenticates skill users. Requests confirmation for accessing data in the Aqara app. Generates a token. The token is passed to the skill, and the skill sends it in requests to Aqara.

Scenarios for developing an authorization-based skill:

You develop your own resource server and authorization server

You independently implement an authorization server to run OAuth 2.0. The authorization server will authenticate the user, request permission to access their private data, and issue tokens.

Set up communication between the authorization server and resource server. The resource server will process requests from the client, validate tokens, and output the private resource to the skill.

Instead of your own authorization server, you can use the Yango ID to authenticate Yango users. However, note that you can't use Yango authorization for official skills.

In this case, you develop your own resource server, but use a third-party authorization server

The authorization server can be part of your smart device data server (for example, the Aqara app server). As an alternative, you can use a third-party authorization server. For example, for unofficial skills, you can set up external authorization via Yango.

A third-party authorization server can provide the user data to the skill, such as username or email (if the user agrees). This way you can collect statistics about your skill users.

You use both a third-party resource server and a third-party authorization server

You don't have to own an authorization server and a resource server (that hosts the smart device data).

For example, you can make an unofficial skill for the Aqara app with an external API. The skill connects to the API, authenticates the user, and sends requests on behalf of the user based on their voice commands. The app must support OAuth 2.0.

If you use third-party systems, look up the following in their documentation:

Whether the OAuth 2.0 protocol is implemented on the authorization server.
Whether the authorization server supports authorization code grant.
How you can register an OAuth application on the authorization server.
Which URIs to use for authorization requests and OAuth token requests.
How to call the service's API to access the data of a specific skill user.

How authorization works with a skill

When the user taps Link to Yango, Yango Dialogs redirect them to your service's authorization page (authorization endpoint). You specify the URL of this page when linking accounts in the developer console. Yango Dialogs passes the following parameters within the authorization URL:
- state: Authorization state. It is generated by Yango Dialogs to track the authorization process. The authorization server must return this parameter to Yango Dialogs with the same value.
- redirect_uri is the page where the authorized user is redirected (redirect endpoint). Specify the Yango Dialogs URI as redirect_uri: https://social.yango.com/broker/redirect.
- response_type: Authorization type. Accepts the value of the code.
- client_id: The identifier of your OAuth app.
- scope: An access scope to be granted to the requested OAuth tokens (access token scope). For example: read, home:lights. To specify multiple accesses, separate them with &.
The user enters the username and password for their account on your service.
The authorization server verifies the data entered by the user. If successful, it generates the code to get the token.
The authorization server calls the Yango Dialogs URI https://social.yango.com/broker/redirect. In the request, the server passes the parameters: code, state, client_id, and scope. The authorization server must return them with the same values that Yango Dialogs passed to the authorization URL (see Step 1).
Yango Dialogs uses the code to get an OAuth token and a refresh token for the user account. For this purpose, Yango Dialogs sends requests to the URL you specified when creating authorization in the developer console (in the Get token URL and Refresh token URL fields).
The maximum response length is 5000 characters, and the maximum length of the OAuth token or refresh token is 2048 characters. The token lifetime (the expires_in property) must be an integer between 1 and 4,294,967,296.
Yango Dialogs saves the OAuth token and refresh token (if any). The accounts are now linked.