Volt API
© 2017 NS BASIC Corporation. All rights reserved.
The Volt API is REST API consisting of a core and plug-ins. The core consists of Authentication and User endpoints. Plug-ins add different functions based on the the core.
The core API also exposes /api/client/volt.min.js which provides a friendly JavaScript interface for clients.
Authenticating
Requests that require authentication require the access_token retrieved from the login endpoint to be included in the HTTP Authorization header. If your access_token is abc123, then your header would look like this: Authorization: Bearer abc123.
If you use the client library, this is handled automatically.
Error responses
Some error responses include additional information in the response body. You can read more about in handling errors.
Authentication ¶
None of these methods require an authentication token.
Register ¶
RegisterPOST/api/auth/register
Register for an account. Expects JSON containing the requested email (username), password, and confirmation. An optional scope allows this endpoint to be used by app authors to automate registration for their app users. scope is an app ID, but called scope to maintain consistency with the rest of the authentication group which itself is attempting to maintain compatibility with the OAuth2 spec.
This endpoint triggers a confirmation email upon success if a confirmation_url is defined for the scope (app). This can be done via the dashboard.
It is possible to register without a password, by setting both the password and confirmation to null. A password reset will be triggered as opposed to a confirmation.
Example URI
Headers
Content-Type: application/jsonBody
{
"email": "gh@nsbasic.com",
"password": "insecure",
"confirmation": "insecure",
"scope": "Q4VBZVgw"
}201Headers
Content-Type: application/jsonBody
{
"id": "DA6gHVdJ",
"email": "gh@nsbasic.com",
"confirmed": false,
"admin": false
}402Returned if the app the scope refers to is not a subscriber app.
404Returned if the app the scope refers to is not found.
406Returned if the request’s Content-Type is not application/json.
409Returned if the email has already been registered under this scope.
422Returned if there’s a problem with the request body (including an undecodeable app ID passed in scope). Also if the password is too weak.
500Returned if there was a server error.
Login ¶
LoginPOST/api/auth/login
This endpoint is based on the OAuth2 spec so we can transition if needed. Specifically, this follows Section 4.3 Resource Owner Password Credentials Grant with the exception that requests are made using the JSON rather than form encoding. scope is required and should correspond to an app ID to authenticate against.
Example URI
With ScopeHeaders
Content-Type: application/jsonBody
{
"grant_type": "password",
"username": "gh@nsbasic.com",
"password": "insecure",
"scope": "oAyLuW0e"
}200Returned if the login succeeded. Returns a bearer token per OAuth2 Section 5.1. The access token is a JWT. The user_id is additionally returned so it can be used in future requests (without an additional API call).
Headers
Content-Type: application/jsonBody
{
"access_token": "[Valid JWT]",
"token_type": "bearer",
"expires_in": 3600,
"user_id": "xDe3f5c"
}401Returned if the login failed.
402Returned if the app the scope refers to is not a subscriber app.
403Returned if the account is unconfirmed and a confirmation_url is defined for the scope (app).
404Returned if the app the scope refers to is not found.
406Returned if the request’s Content-Type is not application/json.
422Returned if there was a problem with the content of the request body or the scope could not be decoded.
500Returned if there was a server error.
Forgot Password ¶
Forgot PasswordPOST/api/auth/forgot
Posting to this endpoint sends an email to the user with a reset password link. In order to function, the associated app must define said link (via the dashboard). If no link is defined, this endpoint returns an error (501).
Example URI
Headers
Content-Type: application/jsonBody
{
"email": "gh@nsbasic.com",
"scope": "oAyLuW0e"
}204Returned if there was no problem with the request. This does not confirm or deny account validity.
402Returned if the app the scope refers to is not a subscriber app.
404Returned if the app the scope refers to is not found.
406Returned if the request’s Content-Type is not application/json.
422Returned if there was a problem with the content of the request body or the scope could not be decoded.
500Returned if there was a server error.
501Returned if the reset_url is not defined for the associated app.
Resend Confirmation ¶
Resend ConfirmationPOST/api/auth/resend
Posting to this endpoint re-sends a confirmation email to the user if the user is unconfirmed.
Example URI
Headers
Content-Type: application/jsonBody
{
"email": "gh@nsbasic.com",
"scope": "oAyLuW0e"
}204Returned if there was no problem with the request. This does not confirm or deny account existence.
402Returned if the app the scope refers to is not a subscriber app.
404Returned if the app the scope refers to is not found.
406Returned if the request’s Content-Type is not application/json.
422Returned if there was a problem with the content of the request body or the scope could not be decoded.
500Returned if there was a server error.
501Returned if the confirmation_url is not defined for the associated app.
Reset Password ¶
Reset PasswordPOST/api/auth/reset
Reset a password given a valid confirmation token.
Example URI
Headers
Content-Type: application/jsonBody
{
"token": "reset token",
"password": "newpass",
"confirmation": "newpass"
}204Returned if the reset was successful
401Returned if the token can’t be authenticated, is expired, or malformed.
406Returned if the request’s Content-Type is not application/json.
422Returned if the password and confirmation do not match, if there is a problem with the request body, or if the password is too weak.
500Returned if there was a server error.
Confirm Account ¶
Confirm AccountPOST/api/auth/confirm
Confirms an account given a confirmation token. The token encodes all information about the account being confirmed. The token is passed as part of the confirmation URL. It is up to the application to process the token and call this endpoint. Upon successful the associated user’s account will be marked confirmed.
Example URI
Headers
Content-Type: application/jsonBody
{
"token": "confirmation token"
}204Returned if the confirmation was successful.
401Returned if the token can’t be authenticated, is expired, or malformed.
406Returned if the request’s Content-Type is not application/json.
422Returned if there is a problem with the request body.
500Returned if there was a server error.
Users ¶
These endpoints deal with managing a user’s account, defaulting to the currently logged in user. These routes require authentication.
Users emails (usernames) are unique within the context of the associated app, but can be duplicated across the system. For example: gh@nsbasic.com can have accounts for helloworld.volt.live and testapp.volt.live.
Current User ¶
Get user detailsGET/api/user/{userid}
Returns JSON containing the user’s details.
Example URI
- userid
string(optional) Example: DA6gHVdJuser to work with, defaults to the currently logged in user
Headers
Authorization: Bearer [Valid JWT]200Returns information about the user.
Headers
Content-Type: application/jsonBody
{
"id": "DA6gHVdJ",
"email": "gh@nsbasic.com",
"confirmed": true,
"admin": true,
"first_name": "George",
"last_name": "Henne"
}401Returned if the authentication (JWT) is missing or invalid.
404Returned if the user ID is not found (or the logged in user does not have access).
422Returned if the user ID is undecodable.
500Returned if there was a server error.
Update user detailsPUT/api/user/{userid}
Allow any of the user details (including password) to be updated. Only passed attributes will be updated, however, if password is included, old_password and confirmation must also be included. The admin attribute (see above) is read-only and cannot be updated. The confirmed attribute is read-only and must be updated via the confirmation process. You must pass at least one property to be updated. Currently, you can only update your own user record.
Example URI
- userid
string(optional) Example: DA6gHVdJuser to work with, defaults to the currently logged in user
Headers
Content-Type: application/json
Authorization: Bearer [Valid JWT]Body
{
"email": "new@email.com",
"password": {
"old": "myOldPassword",
"new": "myNewPassword",
"confirmation": "myNewPassword"
}
}200Returned if the update was successful. Returns the updated user object.
Body
{
"id": "DA6gHVdJ",
"email": "gh@nsbasic.com",
"confirmed": true,
"admin": true,
"first_name": "George",
"last_name": "Henne"
}401Returned if the authentication (JWT) is missing or invalid.
403Returned if the old password is incorrect.
404Returned if the user ID is not found or the logged in user does not have access.
406Returned if the request’s Content-Type is not application/json.
409Returned if the email is already in use by another user for the associated app.
422Returned if the password and confirmation do not match, if there is a problem with the request body, or if the user ID is undecodeable. Also if the password is too weak.
500Returned if there was a server error.
Delete accountDELETE/api/user/{userid}
Delete the account.
Example URI
- userid
string(optional) Example: DA6gHVdJuser to work with, defaults to the currently logged in user
Headers
Authorization: Bearer [Valid JWT]204Returned if the account was deleted successfully (invalidating all tokens).
401Returned if the authentication (JWT) is missing or invalid.
404Returned if the user ID is not found or the logged in user does not have access.
409Returned if the user has associated apps that must be deleted first.
422Returned if the user ID is undecodable.
500Returned if there was a server error.
Email Plug-in ¶
© 2017 NS BASIC Corporation. All rights reserved.
In order to use this endpoint an API key and from address must be configured for the app in the Volt Dashboard. Currently, only SendGrid is supported as an underlying email provider.
Email Endpoint ¶
Email EndpointPOST/api/email
Send an email to the currently authenticated user.
Example URI
Headers
Content-Type: application/json
Authorization: Bearer [Valid JWT]Body
{
"subject": "Thanks for signing up!",
"text": "Dear User\nThanks for signing up!\n- App Owner"
}200Returned if the message was sent successfully.
401Returned if the authentication (JWT) is missing or invalid.
406Returned if the request’s Content-Type is not application/json.
422Returned if the request JSON was invalid.
500Returned if there was a server error.
501Returned if email_from or email_api_key are not set (via the Dashboard).
Storage Plug-in ¶
© 2017 NS BASIC Corporation. All rights reserved.
All calls include a scope (either an app or user ID at the moment). All calls include checks to make sure the user has access. Access currently falls under two scopes:
-
App Based - the app owner has read/write, app users have read. Useful for global app settings that can be public.
-
User Based - the user has read/write (app owner of course has read/write as well).
Keys length must be less than or equal to 255 characters.
Key based access ¶
RetrieveGET/api/storage/{scope}/key/{key}
Example URI
- scope
string(required) Example: Q4VBZVgwscope to use for storage requests
- key
string(required)key to perform the action on
Headers
Authorization: Bearer [Valid JWT]200Returns valid JSON.
Headers
Content-Type: application/jsonBody
"this is the value"401Returned if the authentication (JWT) is missing or invalid.
404Returned if the scope or key is not found, or the user does not have access.
422Returned if the scope can’t be decoded or if the key is too long.
500Returned if there was a server error.
Create or UpdatePUT/api/storage/{scope}/key/{key}
The body of this request should be valid JSON.
Example URI
- scope
string(required) Example: Q4VBZVgwscope to use for storage requests
- key
string(required)key to perform the action on
Headers
Content-Type: application/json
Authorization: Bearer [Valid JWT]Body
"this is the value"204Returned if the create/update was successful.
401Returned if the authentication (JWT) is missing or invalid.
404Returned if the scope is not found or the user does not have access.
406Returned if the request’s Content-Type is not application/json.
422Returned if the scope can’t be decoded or if the key is too long.
500Returned if there was a server error.
DeleteDELETE/api/storage/{scope}/key/{key}
Example URI
- scope
string(required) Example: Q4VBZVgwscope to use for storage requests
- key
string(required)key to perform the action on
Headers
Authorization: Bearer [Valid JWT]204Returned if the deletion was successful or if there was nothing to delete.
401Returned if the authentication (JWT) is missing or invalid.
404Returned if the scope is not found or the user does not have access.
422Returned if the scope can’t be decoded or if the key is too long.
500Returned if there was a server error.
Miscellaneous Endpoints ¶
Get all itemsGET/api/storage/{scope}
Example URI
- scope
string(required) Example: Q4VBZVgwscope to use for storage requests
Headers
Authorization: Bearer [Valid JWT]200Returns all items stored in a JSON object or an empty object
Body
{
"key1": "value1",
"key2": "value2"
}401Returned if the authentication (JWT) is missing or invalid.
404Returned if the scope is not found or the user does not have access.
422Returned if the scope can’t be decoded.
500Returned if there was a server error.
Clear all itemsDELETE/api/storage/{scope}
Example URI
- scope
string(required) Example: Q4VBZVgwscope to use for storage requests
Headers
Authorization: Bearer [Valid JWT]204Returned if the deletion was successful, or if there were no items to delete.
401Returned if the authentication (JWT) is missing or invalid.
404Returned if the scope is not found or the user does not have access.
422Returned if the scope can’t be decoded.
500Returned if there was a server error.