Authentication

Authentication in the OnSong API requires a permitted user token. This token is generated by the 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.

Check authentication

URL/api/<auth_token>/auth
MethodGET
Version1.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
MethodPUT
Version1.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
MethodDELETE
Version1.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
MethodGET
Version1.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"
}