Welcome to ToneDen's API! Here we'll go over what you'll need to do in order to get started building on our platform. Follow the steps below to create a ToneDen account and an app that you will use to access our API.

Create Your Account

All apps that interact with the ToneDen API must be affiliated with a ToneDen account. You can create a ToneDen account here. If you already have an account with us, you can log into it and proceed to the next step.

Create Your App

To work with the ToneDen API, you'll need to create an app in your Developer Settings. Your app must have a name, logo, and URL, which will be displayed on the OAuth 2.0 authorization dialog when a user is prompted to grant your application access to their ToneDen account. You must also specify one or more OAuth redirect URIs, which are URLs that users will be redirected to after granting your application access to their ToneDen accounts.

Once you've created an app in your Developer Settings, you will receive a Client ID and Client Secret. It is imperative that you store your Client Secret in a secure location immediately, as it is not accessible once you close the confirmation dialog after creating your app. Treat it as a password and do not check it into source control.

Your app will need to be reviewed by our team to ensure that your use case complies with our API policies before you are able to use the API. You may be contacted by our review team over email, so make sure your ToneDen account has an accurate email address attached to it.

Obtain User Access Tokens

All requests to the ToneDen API must be authenticated with a user access token. You can obtain user access tokens via the OAuth 2.0 protocol. Our system currently only supports the Authorization Code flow, which entails the following steps:

• Your app routes the user's browser to
  https://www.toneden.io/auth/oauth2/authorize?response_type=code&client_id=<your app's client ID>&redirect_uri=<your app's redirect URI>
• ToneDen displays your app's information in an authorization prompt
• The user accepts the authorization prompt and is redirected back to
  <your redirect URI>?code=<authorization code>
• Your app passes the authorization code back to our token endpoint in the body of a POST request:

curl -X POST 'https://www.toneden.io/auth/oauth2/token' \
--header 'Content-Type: application/json' \
--data-raw '{
  "grant_type": "authorization_code",
  "code": "<your authorization code>",
  "redirect_uri": "<your redirect URI>",
  "client_id": "<your client ID>",
  "client_secret": "<your client secret>"
}'

• ToneDen sends back a JSON response containing the user's access token:

{
  "access_token": "<user access token>",
  "token_type": "Bearer"
}

We highly recommend using an existing OAuth framework compatible with your server architecture, such as Passport for node.js.

A detailed description of the OAuth 2.0 protocol is beyond the scope of our documentation, and there are many resources available online which explain it clearly. If you are unfamiliar with OAuth 2.0, we recommend starting here.

Authenticate Requests

Once you've successfully retrieved a user access token, you can make API calls as the user by including it in the Authorization header after the text "Bearer". For example, the following request would retrieve information about the user to whom the access token belongs:

curl https://www.toneden.io/api/v1/users/me
--header "Authorization: Bearer <access token>

We're here to help!

Running into trouble? Got a question about an endpoint? Feel free to reach out to us at [email protected].