Authentication

Authentication in the OnSong^® Connect API allows the user to authorize use of their library by third-parties. Additionally, it requires OnSong LLC to authorize use of the API by third-parties. This combination builds a system of trust between the end user and then integration developer.

Authentication in the OnSong^® Connect API requires a permitted user authentication token. This token is generated by your client application and must be 32 characters or more in length. This is passed as the first path argument with each call to the API that must be authenticated.

The API key you receive from OnSong will be passed as a parameter on each call to the API endpoints to verify your use of the OnSong^® Connect API. While required to authenticate the user token, passing it on each call will automatically extend the 30-day expiration of the authentication token, making for a seamless experience for the user.

Passing API Keys

To use OnSong^® Connect and other APIs and SDKs made available by OnSong LLC, you'll need an API key. This is what uniquely identifies your application with OnSong Developer Resources. If you don't already have an API key, please request one before proceeding.

If you have an API key, you will want to pass it as a parameter via the query string or within the body of the request. While this is important for the initial authentication methods, it should be passed with every call to handle the case where the authentication token is expired.

Note: the host device requires a connection to the Internet in order to verify the API key. Authorization tokens expire in 30 days if the API key is not encountered.

Check authentication

URL	/api/<auth_token>/auth
Method	GET
Version	1.0

Description

Tests the authentication status of the user token.

Path arguments

Name	Type	Description	Required
auth_token	string	The authentication token used to authenticate the request.	Required

Response

Returns a basic response code to determine the success or failure of the operation.

Response example

Success is indicated by the existence of the "success" parameter.

{
		"success" : "Token Registered"
	}

Errors are indicated by the existence of the "error" parameter and can be either "No Token", "Invalid Token Length" or "Not Registered".

{
		"error" : "Not Registered"
	}

Add user to whitelist

URL	/api/<auth_token>/auth
Method	PUT
Version	1.0

Description

Registers The authentication token into the API whitelist if the API OnSong instance is accepting new users. Call this method if The authentication token was not registered.

Path arguments

Name	Type	Description	Required
auth_token	string	The authentication token used to authenticate the request.	Required

Body arguments

Name	Type	Description	Required
name	string	The name of the device that is attempting to connect. If omitted, the authentication token is displayed to the end user.	Optional

Response

Returns a basic response code to determine the success or failure of the operation.

Response example

Success is indicated by the existence of the "success" parameter with the following values "Token Registered" or "Token Accepted".

{
		"success" : "Token Accepted"
	}

Errors are indicated by the existence of the "error" parameter and can be either "No Token", "Invalid Token Length" or "Not Accepting Users".

{
		"error" : "Not Accepting Users
	}

Notes

If "Not Accepting Users" is returned, the API OnSong instance should prompt the user to accept an incoming connection. Once the user has allowed incoming user authentication requests, this method should be called again to add the user to the whitelist.

Delete user from whitelist

URL	/api/<auth_token>/auth
Method	DELETE
Version	1.0

Description

Removes The authentication token from the API whitelist.

Path arguments

Name	Type	Description	Required
auth_token	string	The authentication token used to authenticate the request.	Required

Response

Returns a basic response code to determine the success or failure of the operation.

Response example

Success is indicated by the existence of the "success" parameter with the following value "Token Unregistered".

{
		"success" : "Token Unregistered"
	}

Errors are indicated by the existence of the "error" parameter and can be either "No Token", "Invalid Token Length" or "Token Not Found".

{
		"error" : "Invalid Token Length"
	}

Device information

URL	/api/<auth_token>/myself
Method	GET
Version	1.0

Description

Retrieves information about the current device.

Path arguments

Name	Type	Description	Required
auth_token	string	The authentication token used to authenticate the request.	Required

Response

Returns basic information about the device that is hosting the OnSong Connect services.

Response example

The following information is available about the OnSong Connect server.

{
		"name": "My iPad",
		"endpoint": "http://192.168.1.15:5076/api",
		"model": "iPad",
		"token": "01234567-89AB-CDEF-0123-456789ABCDEF"
	}