API Key Authentication
Opensubsonic:
OpenSubsonic version: 1
OpenSubsonic extension name apiKeyAuthentication (As returned by getOpenSubsonicExtensions)
Version 1
This extension requires changes to the semantics of authentication. Broadly, there are two general changes:
- Required: A new authentication mechanism:
apiKeyfor query. - Recommended: Deprecation of token/salt-based authentication.
API keys
An API key is any authentication token generated by an OpenSubsonic server that can be used to authenticate. How this API key is generated by the server is implementation-specific: the server may provide a page where the user can configure one or more API keys, the server may automatically generate a API key, or any other variety of means. The format of the API key is not specified, but it must be of reasonable length to fit into a query parameter (less than 2048 characters URL-encoded).
Servers which implement this extension must provide some mechanism for viewing active API key(s) and allow for revoking API keys. Note that these API keys do not expire; as long as they are not revoked by the user, they are assumed to be valid.
Using a API key
An API key is used as a query parameter apiKey=<api key>.
When an API key is provided, the client must not provide a u parameter; passing in u must be treated as an error 43.
It is recommended that servers which provide API-key authentication no longer support salt/token-based authentication.
If multiple conflicting authentication parameters are passed in, the server must return an error 43, Multiple conflicting authentication mechanisms provided
If a server removes support for token-based authentication, it must return error 41 (Token authentication not supported for LDAP users.).
If a server removes support for any other particular authentication mechanism, it must return an error 42 (Provided authentication mechanism not supported).
In both cases, it is recommended that the server provide a meaningful url (configuration url, documentation, etc) in the helpUrl to help clients instruct their users how to obtain an API key.
New error codes
This extension introduces three new errors 42, 43 and 44, and adds a new field helpUrl. See error