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. On OnSong 2026 and newer, the token can instead be passed as an HTTP header — see Passing credentials via HTTP headers below.

The API key you receive from OnSong will be passed 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 the api_key parameter via the query string for GET or HEAD methods, or within the body of the request for all others. 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.

GET /api/<auth_token>/songs?api_key=<api_key>

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.

Passing credentials via HTTP headers

OnSong 2026 and newer also accepts both credentials as standard HTTP headers, which keeps them out of URLs, request logs, and browser history. The authentication token is passed as a bearer token in the Authorization header, and the API key is passed in the X-OnSong-API-Key header:

Authorization: Bearer <auth_token>
X-OnSong-API-Key: <api_key>

When the Authorization header is supplied, the token is read from the header instead of the URL. The <auth_token> path argument shown in the endpoints below must still be present in the URL, but can be replaced with a placeholder such as an underscore. For example, the two requests below are equivalent:

GET /api/<auth_token>/songs?api_key=<api_key>

GET /api/_/songs
Authorization: Bearer <auth_token>
X-OnSong-API-Key: <api_key>

Note: header-based authentication requires the device to be running OnSong 2026 or newer. Older versions ignore these headers, so if your integration must support earlier releases, continue to pass the authentication token as a path argument and the API key as an api_key parameter. You can determine the OnSong version from the version value in the device's Bonjour TXT record.

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"
	}