Authentication
The Samply API uses personal access tokens to authenticate requests.
Your Access Tokens carry many privileges, so be sure to keep them secure. Don't share your tokens in publicly accessible places like GitHub or client-side code.
Authentication to the API is performed with HTTP Token Auth. Provide your token as a parameter in the Authorization header with "auth-scheme" set to Bearer.
Authorization: Bearer <Your Token>Create and manage your tokens here: samply.app/preferences/api
INFO
Our API is currently availble on team plans & upon request. We can work with you to create custom solutions and expand the API wherever necessary.
OAuth Support
If you're interested in building a Samply integration through your service, you'll need a way to connect a Samply token with your user's Samply account. OAuth is an open standard that offers a secure way for users to grant applications access to their information.
Currently, Samply offers OAuth support directly. If you're interested in implementing OAuth in your integration, please reach out to our lead software engineer at matt@samplyaudio.com.
OAuth Implementation
Once you've worked with our team and received a CLIENT_ID and CLIENT_SECRET, you'll need to implement OAuth in your application. Below, we've provided a general example of that implementation.
Authorization request
First, your application will need to redirect the user to Samply so the user may authorize the connection between your service and Samply. In the request, you must provide the CLIENT_ID ans redirect_uri. All other parameters are optional.
https://samply.app/oauth/yourservice?client_id=MYCLIENT_ID&redirect_uri=REDIRECT_URI&error_uri=ERROR_URI&state=STATE.client_id query parameter
CLIENT_ID as provided to your service by the Samply team.
redirect_uri query parameter
Redirect URI back to your service. User will be redirected here after successfully authorizing the OAuth request.
error_uri query parameter optional
Error URI back to your service. User will be redirected here after an unsuccessful authorization request.
state query parameter optional
Optional state parameter. This value will be passed back to your service after a successful or unsuccessful authorization request.
Authorization grant
If the user declined authorization or another error occurred, Samply will redirect to the error_uri with an error and error_description. You can read more information on error handling here.
If the user successfully granted authorization, Samply will redirect to the redirect_uri. with a code and state (if it was provided).
Request token
Now that the user has authorized the request, your server may request a token from the auth-token endpoint on behalf of that user.
Request type POST
Endpoint /auth-token
{
client_id: string,
client_secret: string,
code: string,
}client_id string
CLIENT_ID as provided to your service by the Samply team.
client_secret string
CLIENT_SECRET as provided to your service by the Samply team. Never expose this value in publicly available code.
code string
The code provided to your server from Samply after user authorization.
Assuming CLIENT_ID, CLIENT_SECRET, and code were all valid, a 200 response will be sent containing that user's access token.
{
access_token: string
}Now that you have a user's access token, you're ready to build an integration that makes calls on their behalf!
Error handling
When a user declines authorization or another error occurs, Samply will redirect to the provided error_uri and provide additional error and error_description query parameters that can be read on your server. Those values are outlined below. If state was provided in the initial request, it will be provided in the error redirect as well.
error query parameter readonly
Error code with the following possible values:
Values
access_denied
User denied authorization.
server_error
Something went wrong on Samply's server during authorization.
error_description query parameter readonly
A human readable, URI-encoded description of the error that occurred.