Authentication

The Auphonic API allows you to authenticate in two different ways. The primary authentication method for web, mobile and desktop applications is to use OAuth 2.0 Authentication. Furthermore it’s also possible to use HTTP Basic Authentication to access your own resources.

HTTP Basic Authentication

You can access all API resources just by using your auphonic username and password.

An example which returns all your productions:

curl https://auphonic.com/api/productions.json -u username:password

Warning

This method is meant only for scripts to authenticate yourself to the API. For all third party applications with multiple users, try to use OAuth 2.0 Authentication!

OAuth 2.0 Authentication

Auphonic authentication primarly uses OAuth 2.0, as an easy way to authenticate third party applications. This authentication method allows you to access a user account on their behalf, without storing the username and password.

See Introducing OAuth 2.0 for a short introduction to OAuth 2.0.

There are two authentication flows available:

OAuth 2.0 Authentication Flow for Web Apps, where it’s necessary to call back a Redirect URI on your server
OAuth 2.0 Authentication Flow for Desktop and Mobile Apps, without the Redirect URI

Please always use the OAuth 2.0 Authentication Flow for Web Apps if possible!

OAuth 2.0 Authentication Flow for Web Apps

To authenticate your web application, the following steps are required:

Step 1: Register an Auphonic App

Register your new application at the Auphonic Apps Page to get a client ID and secret.

Important Field:

Redirect URI: Must be callable on your server to receive a grant code to generate an access token. You can also set the redirect URI in Step 2, if you don’t control the server or if you want to use multiple redirect URIs.

Warning

The Redirect URI should be https!

Step 2: Redirect a User to a Confirmation Page

You must redirect a new user to a confirmation page, where she or he can authorize your application:

https://auphonic.com/oauth2/authorize/?client_id={client_id}&redirect_uri={redirect_uri}&response_type=code

where client_id is the Client ID of your app. The parameter redirect_uri is optional: if you set your redirect URI already in Step 1, then you don’t need to send it again.

After the user authorizes the application, auphonic issues a GET request to the Redirect URI with a grant code for the new user, e.g.:

{redirect_uri}/?code=ce76pSRQg958dzKcAVVNxZ

Step 3: Obtain the Access Token

Now you can use the grant code to obtain the access token, which can be used to access auphonic resources:

curl -X POST https://auphonic.com/oauth2/token/ \
    -F "client_id={client_id}" \
    -F "client_secret={client_secret}" \
    -F "redirect_uri={redirect_uri}" \
    -F "grant_type=authorization_code" \
    -F "code={grant_code}"

where client_secret is the Client Secret of your App and grant_code is the code your received in Step 2.

Note that the redirect_uri is required here. You have to use the one you entered at the client registration page, or the one you send at the first request.

If the request is issued correctly, you receive a response with the access token, e.g.:

{
    "access_token": "436bfd6bed",
    "token_type": "bearer",
    "expires_in": 315360000,
    "user_name": "my_auphonic_username",
    "scope": ""
}

Step 4: Use the Access Token for Auphonic API Requests

To access auphonic resources, just add the access token to the authorization header:

curl https://auphonic.com/api/productions.json -H "Authorization: Bearer {access_token}"

or to a GET parameter (for streaming audio files, loading pictures, etc.):

curl https://auphonic.com/api/productions.json?bearer_token={access_token}

OAuth 2.0 Authentication Flow for Desktop and Mobile Apps

This authentication flow should be used, if it is not possible to callback a Redirect URI on your client. Whenever possible, please prefer the OAuth 2.0 Authentication Flow for Web Apps!

The following steps are required for the desktop/mobile authentication flow:

Step 1: Register an Auphonic App

Register your new application at the Auphonic Apps Page to get a client ID and secret.

Important Fields:

Public: select public to promote your App to other auphonic users.
Redirect URI: not required for desktop/mobile apps!

Step 2: Obtain the Access Token with user credentials

You have to use the user credentials to obtain the access token:

curl -X POST https://auphonic.com/oauth2/token/ \
    -F "client_id={client_id}" \
    -F "username={username}" \
    -F "password={password}" \
    -F "grant_type=password" \
    -u {client_id}:{client_secret}

where client_id and client_secret is the Client ID and Secret of your App and username/password are the credentials of the user.

Warning

Don’t store or misuse the password. Otherwise your app will be removed immediately!

If the request is issued correctly, you receive a response with the access token, e.g.:

{
    "access_token": "436bfd6bed",
    "token_type": "bearer",
    "expires_in": 315360000,
    "user_name": "my_auphonic_username",
    "scope": ""
}

Step 3: Use the Access Token for Auphonic API Requests

To access auphonic resources, just add the access token to the authorization header, e.g.:

curl https://auphonic.com/api/presets.json -H "Authorization: Bearer {access_token}"

or to a GET parameter (for streaming audio files, loading pictures, etc.):

curl https://auphonic.com/api/presets.json?bearer_token={access_token}