Getting an access token

To make requests on behalf of your user, you need to get an OAuth2 access token. There are two type of flow you can use depending on your use case: The OAuth 2.0 Implicit Flow or the OAuth 2.0 Authorization code Flow. Currently access tokens never expire, so this process will be done once per user.

In both cases, you must choose which scopes to request for the access token:

  • voice: the access token will grant you access to the digital voice of the user (and allow you to generate audio from their voice);
  • profile: the access token will grant you access to the profile information of the user, such as their email and display name.

You can choose either or both of these scopes.

OAuth 2.0 Implicit Flow

This flow is mostly used for websites (Single Page Applications) and mobile apps. The OAuth2 authentication flow is:

  • Your application opens the browser of the user to a voice consent form page on our website.
  • The user sees a form with your app name and description, prompting him to give you access to their voice;
  • The user clicks on the accept button and their browser is redirected to the redirect URI you entered in your app form on the OAuth application page;
  • Your website or mobile app receives the request, which contains the access token in the URL. You can extract the access token and use it for your authenticated requests.

The URL you need to redirect/open the browser of the user to is: https://myvoice.lyrebird.ai/authorize

with the following URL query parameters:

  • response_type: This value must be token.
  • client_id: The Client ID of your application, exactly as shown in the Application Page of your app.
  • redirect_uri: The (URL encoded) redirect URI of your application, which must be exactly the same as the one in the Application Page of your app.
  • scope: The scopes you want to request for the access token (as described above): voice, profile, or voice profile to request both.
  • state: A unique, randomly generated opaque ID of your choice for the current authorization request, for security purposes.

Notice the Client Secret is not used for this authorization flow.

For example, to request voice access to a user, with an app whose Client ID is 19qV2jZy1G44ifOxk6kgowAt9F0 and redirect URI is https://www.example.com/auth/lyrebird:

https://myvoice.lyrebird.ai/authorize?response_type=token&client_id=19qV2jZy1G44ifOxk6kgowAt9F0&redirect_uri=https%3A%2F%2Fwww.example.com%2Fauth%2Flyrebird&scope=voice&state=987654321

After the user clicks on the accept button, their browser will be redirected and will make a request to the redirect URI you specified. The following URL fragment parameters will be appended to the request:

  • state: An opaque ID which must be the same as the one you sent in the previous request. If this parameter is omitted or empty, or does not match the one you sent, you must ignore this request, which was probably forged by a malicious third-party.
  • access_token: The OAuth2 access token of the user. This is the token you will use to make all authenticated API requests on behalf of the user. You must keep this value private as it lets anyone access the account of the user.

For example, with the same redirect URI as before, https://www.example.com/auth/lyrebird, the user would be redirected to:

https://www.example.com/auth/lyrebird#access_token=18QdNlaDvkzMbgQ5SXmKNGmexWo&state=987654321

Notice that # is used rather than ?.

OAuth 2.0 Authorization code Flow

This flow is mostly used for server-side apps.

The OAuth2 authentication flow is:

  • Your app redirects/opens the browser of the user to a voice consent form page on our website;
  • The user sees a form with your app name and description, prompting him to consent giving you access to their voice;
  • The user clicks on an accept button and their browser is redirected to the redirect URI you entered in your app form on the OAuth application page;
  • Your server receives the HTTP request, which contains an OAuth2 authorization code in the URL. This authorization code is only valid for a few minutes and lets you request an access token as in the next step. It has no other uses.
  • Your server makes an HTTP request to the Lyrebird API to exchange the authorization code for an access token.
  • Your server receives an HTTP response from the API, containing the access token of the user, to use for your authenticated requests.
Getting the authorization code

The URL you need to redirect/open the browser of the user to is: https://myvoice.lyrebird.ai/authorize

You must add these URL query parameters:

Parameter Description Required
response_type The value of this field must be code Yes
client_id The Client ID of your application, exactly as shown in the Application Page of your app. Yes
redirect_uri The URI your users will be sent back to after authorization. This value must match one of the defined OAuth 2.0 Redirect URLs in your application configuration Yes
scope The "scope" you ask right for: voice, profile or both space separated Yes
state A unique, randomly generated opaque ID of your choice for the current authorization request, for security purposes Yes

For example, to request voice access to a user, with an app whose Client ID is 19qV2jZy1G44ifOxk6kgowAt9F0 and redirect URI is https://www.example.com/auth/lyrebird:

https://myvoice.lyrebird.ai/authorize?response_type=code&client_id=19qV2jZy1G44ifOxk6kgowAt9F0&redirect_uri=https%3A%2F%2Fwww.example.com%2Fauth%2Flyrebird&scope=voice&state=987654321

After the user clicks on the accept button, their browser will be redirected and will make a request to the redirect URI you specified. The following URL query parameters will be appended to the request:

  • state: An opaque ID which must be the same as the one you sent in the previous request. If this parameter is omitted or empty, or does not match the one you sent, you must ignore this request, which was probably forged by a malicious third-party.
  • code: The OAuth2 authorization code for this current authorization flow, that you will exchange for an access token in the next step.

For example, with the same redirect URI as before, https://www.example.com/auth/lyrebird, the user would be redirected to:

https://www.example.com/auth/lyrebird?code=19qozJe3hwnPvfl5xyNuR3MJ1NK&state=987654321

Converting the authorization code to an access token

You can then make an HTTP POST request to the Lyrebird API to exchange the authorization code for an access token.

POST https://avatar.lyrebird.ai/api/v0/token

Parameter Description Required
grant_type The grant type should always be authorization_code Yes
code The OAuth2 authorization code you received in the previous step Yes
client_id The Client ID of your application, exactly as shown in the Application Page of your app Yes
client_secret The Client Secret of your application, exactly as shown in the Application Page of your app. You must keep this value private (on your server). If you cannot do this request without otherwise keeping this value private, you must use the flow for web apps described above instead. Yes

The server will respond with a JSON object containing:

  • access_token: The OAuth2 access token of the user. This is the token you will use to make all authenticated API requests on behalf of the user. You must keep this value private as it lets anyone access the account of the user.

For example, using the same credentials as above:

CURL
# Request #
curl -H 'Content-Type: application/json'
'https://avatar.lyrebird.ai/api/v0/token' -d
'{
    "grant_type": "authorization_code",
    "client_id": "19qV2jZy1G44ifOxk6kgowAt9F0",
    "client_secret": "19qnfRvIXdmQKhSbLG0CLxng5Mz",
    "code": "19qozJe3hwnPvfl5xyNuR3MJ1NK"
}'
# Response #
{
    "access_token": "18QdNlaDvkzMbgQ5SXmKNGmexWo"
}

results matching ""

    No results matching ""