Developer Center

Public API

Saber includes a public REST API which can be used from 3rd-party applications to execute various commands and retrieve data about your website. To use Saber's public API, the 3rd-party application must make URL requests to https://{your-saber-domain.com}/api/{ServiceClassName}/{ServiceMethodName} using the POST method and must use a developer key in the POST parameters.

Developer Keys

To authenticate 3rd-party applications, Saber requires that all API requests come from a secure web server and include the POST parameter apikey, which must contain the key value from one of the developer-keys found within Saber's config.json file.

{
"developer-keys": [
{
"client_id": "my-3rd-party-app",
"key": "YoUr2KeY4GoEs6HeRe8",
"userId": 162,
"host": "https://my-3rd-party-app.com",
"redirect_uri": "https://my-3rd-party-app.com/saber-auth/
}
]
}

The above example shows a developer key within the config.json file. We suggest that you generate a developer key for each 3rd-party application that you wish to allow access to Saber's public API endpoints, and generate keys that contain random alpha-numeric characters using at least 16 characters.

The client_id property is the ID used by the 3rd-party application to retrieve an authorization request.

The key property should be a alpha-numeric string less than 64 characters in length

The userId property (optional) will link to a user account and will use this user account and associated security keys when accessing a public API endpoint if you do not wish to use a token to authenticate users using oAuth 2.0.

The host property must match the host that is making the API request

The redirect_uri property is the URL used to redirect the user to after an authorization request has been made.

You can change the developer key within your config.json at any time, but you will be required to update the developer key within the 3rd-party application as well.

User Authentication

The following instructions are meant for 3rd-party applications to authenticate a Saber user account using OAuth 2.0.

Some API endpoints are secure and will require user permissions before execution. Therefore, 3rd-party applications will need to require their users to log into their Saber account to execute secure, public API endpoints. Use the following process to retrieve & store a persistent token for your user.

For Web Applications

Redirect the user to Saber's internal login page (e.g. https://{your-saber-domain.com}/login?client_id={your-developer-client_id}).
The user will log into their Saber account and redirect back to your website based on the redirect_uri property associated with your client_id found within the config.json file.
Upon being redirected back to your website, the URL will contain a code parameter in the query string that your 3rd-party application will need to send to its web server via JavaScript to complete user authentication.
Make a POST request to Saber's web server from your 3rd-party application web server (e.g. https://{your-saber-domain.com}/api/User/Token) using the code parameter along with the apikey parameter to retrieve a persistent access token for your user.
Store the persistent access token within your user's account to use later. Access tokens will eventaully expire after 365 days.
When accessing a secure Public API via the POST method from your 3rd-party application, include the token parameter associated with your user's account along with the apikey parameter.
When the access token eventually expires, retrieve a new access token by making a POST request to Saber's web server from your 3rd-party application web server (e.g. https://{your-saber-domain.com}/api/User/NewToken) using the oldtoken parameter along with the apikey parameter.

Endpoints

Saber has many internal API endpoints, but only a few are made available for public access. Some plugins may include public API endpoints, but you will need to consult the documentation for those plugins in order to understand which endpoints are available.

api/User/SignUp

Create a new user account with minimum permissions. The new user will be sent an authentication email and will be required to click the authentication link within the email before they are able to log into their Saber account.

POST Parameters

Parameter	Data Type	Description
name	string	User's public display name (e.g. John Doe).
emailaddr	string	User's email address. Primarily used for sending an authentication email as well as logging into their account.
password	string	The user's password, which must adhere to Saber's password policies and may vary since the password policies can be changed by a webmaster.
password2	string	The user's password supplied a second time to ensure that the user correctly typed in their password twice.

Response

success

api/User/RequestActivation

Send an email to the user's email account that will allow them to activate their account.

POST Parameters

Parameter	Data Type	Description
email	string	User's email address.

Response

success