Web API
The HTTP APIs exposed by the scrambls system follow a RESTful pattern. They are divided into calls that require user authentication and calls that don't require user authentication. All calls, however, require a valid API key (issued to partner organizations). The calls that require authentication must pass an authentication token (auth token) that is returned during either the web-app-level authentication process or the authentication of an anonymous UUID. This auth token is passed in an HTTP header (“x-xloak-authtoken”). Authenticated calls fall under https://host/api and unauthenticated calls are under https://host/upi (for “unauthenticated programming interface”), where “host” is “scrambls.com”.
All /api/* calls are checked for a valid auth token and if there is no auth token or the token presented is not valid (meaning that it isn't a known auth token or it's expired), a 403 code is returned along with the JSON {"message":"Not Authorized","result":"OK"}.
Calls to /upi/* are not checked for a valid auth token—except for a few exceptions—and all of those APIs are dispatched immediately. Additionally, two of the unprotected APIs actually require an API key.
API calls that are POSTed to or PUT to require the data to be in JSON format so there must be an HTTP header present in the request like the following:
Content-Type: application/json
All data returned from APIs is in JSON format. Make sure that an A ccept: application/json header is part of the request.
The API key value must be passed in an HTTP header with the name of x-xloak-k. The actual value to be put in this header is supplied by Wave and should be configured into the client code. This API key should be protected and not given out to other developers/SDK users.
New CreateUserPolicy GetUserAccounts
Server Interface
| request |
summary |
| CreateAccount |
Create Account Create Account This API will create a new account and return an account UUID for it. The email address to be used as the account identifer and the ... |
| CreateAuthToken |
Authenticate User Authenticates the given user and returns an auth token that represents that user. The user is identified by email address and the authenticated ... |
| CreateUserPolicy |
Create User Policy Creates a new policy (group). The newly created policy will show up in the "manage groups" list in the dashboard for the user and is in every way ... |
| CreateXID |
Create XID This API creates a new XID and returns it. The actual form of the ID is a decimal number, not a UUID. The creation of the XID requires that the client supply ... |
| DeleteAuthToken |
Delete Auth Token Deletes (invalidates) the given auth token. Any use of the auth token after a successful return from this API will result in a 403 error code being ... |
| DeleteXID |
Delete XID Deletes the given XID. All attempts to get XID Info or to update XID Info on the given XID after this call will fail. Only the XID owner can delete a given ... |
| GetComponentInfo |
Get Component Info Returns information about upgradeable components. URL format: https://host/upi/comp/{id} ?dv a.b.c HTTP Method: GET HTTP Headers ... |
| GetUserAccounts |
Get User Accounts Returns the list of accounts for the user represented by the supplied auth token. URL format: https://host/api/user/account HTTP Method: ... |
| GetUserPolicies |
Get User Policy List Returns information about policies for the user. URL format: https://host/api/userps HTTP Method: GET HTTP Headers: x xloak authtoken: auth ... |
| GetXIDInfo |
Get XID Info Returns information about a particular XID. If the user represented by the auth token supplied is not allowed to descrambl the content as represented ... |
| PostSharedSecret |
Post Shared Secret Adds a new shared secret to the list of secrets entered by the user for decloaking purposes. URL format: https://host/api/secret HTTP Method ... |
| TestAuthToken |
Validate Authentication Token Returns information about the given auth token. This is not an authenticated API (as one might think it could be) because if the client ... |
| UpdateXID |
Update XID This API updates selected information about an existing XID. Because XIDs hold encryption keys that should never be changed (otherwise the content could ... |
Examples
Creating a new account and authenticating that account:
- client code puts the API key the organization was issued into an HTTP header
- client code posts an account creation request to the server with the header and with JSON data that contains the email address and password for the new account
- client code receives a “success” response
- client code puts the API key the organization was issued into an HTTP header
- client code posts an authentication request to the server with the header and with JSON data that contains the email address and password for the new account
- client code receives the authentication token on success and can use that for other operations. Client code can persist the authentication token
Logging out:
- client code puts the API key the organization was issued into an HTTP header
- client code puts the remembered authentication token into an HTTP header
- client code posts an authentication token deletion request (via the HTTP “DELETE” method)
- authentication token is no longer valid
Creating an XID: 1. client code puts the API key the organization was issued into an HTTP header 2. client code puts the remembered authentication token into an HTTP header 3. client code posts an XID creation request to the server with the HTTP headers and with JSON data that contains the policy ID and the key to be associated with the XID 4. client code receives the XID back. | |
