Mechanics
API OVERVIEW
The API enables automated access to and management of data and services on user and account scopes. The API is REST-based with a few concessions for security and simplicity:
- The API client must use the API “auth” command to get a token to use for successive API calls.
- The API authentication code is sent as a secure cookie, rather than using HTTP Basic Authentication. This is because it is not really a username and password and because it is just as easy, if not easier in many cases, to send a cookie.
API INTEGRATIONS
In order to use the API, you must define an “API Integration.” This gives you a unique API public token code and a secret key, specifies the type of authentication that will be used, and allows you to configure the scope and access that will be granted to programs using your API Integration. Your account can have multiple API Integrations configured so that you can use different codes and access levels for different applications or situations.
CREATE AN API INTEGRATION
To create an API Integration:
- Login to your LuxSci account as an account administrator
- Select “Admin – API” from the top menu
- Click on “Add an API Integration”
- Enter a name for the Integration
- Select a “scope” (i.e., is this for users only and will send a username/password as part of the authentication process, or is this for account-level commands and/or commands allowed to perform user-level actions without a username and password?)
- Select the type of API Authentication that you need to use (see below for more details).
- Press “Create Integration”
EDIT YOUR API INTEGRATION
- Login to your LuxSci account as an account administrator
- Select “Admin – API” from the top menu
- Find the API Integration in question
- Click on the “Pencil” icon to view/edit the API Integration details
- Update any settings that you need to change.
- Press “Save Changes”
RETRIEVE YOUR API INTEGRATION KEYS
- Login to your LuxSci account as an account administrator
- Select “Admin – API” from the top menu
- Find the API Integration in question
- Click on the “Pencil” icon to view/edit the API Integration details
- Save the Host, Token, and Secret Key for your application.
API INTEGRATION PROPERTIES
Your API Integration has a number of properties that determine how it works and what you can do with it.
Property
Description
Integration Name
Text description of the API Integration for your own use.
Enabled?
When not enabled, the requests using this API Integration will be rejected.
Scope & Authentication
User Scope: User-level API functions only. Also, a username/password must be passed to gain access to these functions for a specific user. User scope is only recommended for situations where your API client is untrusted (e.g., in a distributed application) and thus you need to collect and use a user’s credentials before any actions should be permitted.
Account Scope: Account-level API functions. Optionally, user-level API functions can also be performed without using a username/password. Account-level access is recommended for server-to-server situations where the API client is trusted. All commands can be accessed from an account-level API Integration without needing individual user credentials.
Authentication: Here, you can specify the type of authentication that will be required for API calls. See below for details. Note that when using the SDKs, the “LuxSci Secure” option must be selected.
API Host
The host name that your API calls must be addressed towards. Use of other host names will be rejected by the API Integration. The default host is “rest.luxsci.com“; you may have a different API host if you have a dedicated API server.
Public Token
Unique API Identifier passed along as part of the authentication phase of API usage.
Secret Key
This unique code is used to verify your access to this API. This should be treated like a very sensitive password and never disclosed or saved in locations that can be viewed by end users. Access to your Token + Key can grant people access to your API.
Limits
- User-level requests/minute.
Maximum number of user-level API requests/minute this API can make across all users. - Account-level requests/minute.
Maximum number of account-level and global-level API requests/minute this API can make across all accounts.
Free Trial accounts have small per-minute and per-day limits that are intended “just for testing things out”.
Accounts using shared services (i.e., shared API/WebMail servers) have larger limits (e.g. 60 requests/minute; 6000 requests/day); these limits can be increased somewhat by support; however, there is a fee for that.
Accounts using dedicated servers, and which have dedicated WebMail, API, and Private Labeling can have their API processed through their own dedicated server; in this case, the API limits can be made very much higher.
Please contact support to inquire about changing your API limits.
Access Controls
(See the section on Access Controls, below)
PROTECT YOUR API INTEGRATION
If you create a program that uses your API, you must be very careful of who can access the API Key and Token! E.g., if you create an application and distribute it, people could garner your Key and Token from the API code and then use your API Integration to do whatever your API is allowed to do. This is a shortcoming of any API.
We have some specific recommendations for you:
- Do not share your API Key and Token with anyone, if you can avoid it.
- If you are making a public application or one that will be distributed out of your control, be sure to only use “user” scope with user name and password authentication required as part of the API authentication process. At least in this way, the API token and key are not useful for doing anything without an additional username and password.
- If you can, restrict what IP addresses will have access to your API (see Access Controls, below).
- Only grant your API Integration permission to do the things that it actually needs to do – and nothing more. This will limit the scope of possible abuse of your API Integration.
- If possible, use the “LuxSci Secure” authentication mechanism, so that your Secret Key never needs to be sent as part of an API call and thus can not be intercepted.
API ACCESS CONTROLS
There are many layers of access controls built into the API. In order for your API requests to function at all:
- The connection must be over TLS (TLS v1.2+ with very good ciphers).
- Your LuxSci account must be active (not closed or disabled).
- Your LuxSci account must have API access granted by Technical Support.
- Your API Integration must exist in your account.
- Your API Integration must be enabled.
- Your connections must be to the assigned API Host.
- Your API credentials (Key and Token) must be correct.
- You must not be exceeding your per-minute or per-day API request limits.
- Your requests must be properly signed (see the Calling the API section, below) when using the “LuxSci Secure” authentication mechanism.
- Your requests most originate from an approved IP address (if you are restricting access by IP).
Additionally, you can control access to your API and the functionality of your API in the Access Control area of your API Interface configuration/ edit screen.
IP ADDRESS ALLOW LIST
The first layer is the IP Address Allow List. This is a list of individual IP Addresses (e.g. 4.2.2.1) or CIDR blocks (e.g. 4.2.2.1/24). When editing your allow list, you can delimit the entries with new lines, spaces, and commas.
Here is how it works:
- If your allow list is empty, the requests can be made from any IP address.
- If the allow list is not empty, then requests can be made only from IP addresses matching at least one of the entries.
- CIDR blocks cannot be more general than “/12”. E.g. “4.2.2.1/24” is OK but “4.2.2.1/10” is not.
Lock API Session to IP
This security setting is available only with “LuxSci Secured” and “OAuth 2.0” authentication mechanisms and it is enabled by default for them.
When enabled, your IP client must present the same IP for API calls that were presented when the authorization token was requested. This prevents the Token from being somehow stolen and used from a different location.
This is very good for security. However, if your API client’s public IP address changes over time, you will need to disable this setting to permit that.
PROTECTED USERS
You can optionally select specific users in your account that will be protected from the API. I.e.,
- All user-scope API commands targeting these users will be rejected
- All account-scope API commands that try to perform account administrative actions on these users will be rejected (this may not include some read-only reporting commands).
User protection is appropriate when you have certain important or administrative users that you want to exclude from API access, or when you do not fully trust your API client.
SCOPE-LEVEL COMMAND ACCESS
Each API scope contains a number of commands. The API provides opt-in access to these commands (for the most part – some read-only operations that do not involve sensitive data — are available generally). This allows you to be very specific about what commands your API can perform and protects you from your API “gaining unwanted access” in the future just because new commands have been added to the API.
Please refer to the API documentation for each level of scope to see what sets of commands can be opted into by your API.
USER AND ACCOUNT SCOPE
All API requests, except authentication and authentication revocation, take place in a “scope” with is either “user” or “account”.
Scope
Description
User
An API Integration whose “scope” is set to “user” must send user authentication information (i.e., username and password) as part of the authentication request. This authentication codes returned can then be only used for user scope commands for the user authenticated. You can use application-specific usernames that have API access (e.g., user@domain.com/api-access) if you have created such in the user security settings pages.
This method of access is appropriate when your application is distributed and you cannot ensure that your API Key cannot be discovered. API calls thus require both that key and the user’s credentials.
This method is also appropriate when you will know the user’s authentication credentials.
All user requests have API URLS that start with: /perl/v2/api/user/[username] where “username” is the login email address (e.g. “joe@domain.com”) of the user with respect to whom the command will apply. The “username” can also be just the user’s unique ID number. Note, while you may use an application-specific username and password (e.g., user@domain.com/api- access) for authentication, the “[username]” in the URL must always be the canonical username (e.g., user@domain.com) or unique ID number.
Account
An API Integration whose “scope” is set to “account” and where you have enabled “Permit user-level commands without username and password” in your API access control settings can also access user-scope commands. In this case, you do not need the user’s authentication credentials and you API client, once authenticated, can make user- scope requests for any permitted user without needing to re-authenticate to change user or scope.
This is appropriate when designing API clients that will manage your account or accounts in an automated manner and where your API Key can be kept safe.
API Integrations explicitly allow one of:
- Only user-scope commands. Such Integrations also require the username and password of the user involved. Because the username and password are required for API access, it is safe to expose the Integration secret key to third parties. I.e., this type of integration is ideal for use insecure situations, such as in publicly deployed applications or code.
- Only account-scope commands.
- both account and user scope commands. This kind of Integration allows you to perform API commands in any scope without needing a user’s password. It is the fullest “administrative mode” and should be used with care.
API URLS BY SCOPE
The API endpoint URLs for user and account scope commands differ. This table shows the difference. Note that the rest.luxsci.com hostname used in the examples may be different for your account.
Scope
Description
User
https://rest.luxsci.com/perl/api/v2/user/[email]/…
[email] will be the login username/email address of the user in question.
Account
https://rest.luxsci.com/perl/api/v2/account/[account_id]/…
[account_id] is the LuxSci account number for the account in question.
This can be found in your API Integration view/edit settings dialog, if you are unsure what it is.
API REQUESTS AND RESPONSES
RESPONSE HTTP HEADERS
The HTTP responses to non-authentication requests include the following response headers:
Content-Type
application/json
X-RateLimit-Limit
X-RateLimit-Remaining
The maximum number of additional requests permitted during the current 1-minute window before a “429” error will be returned.
X-RateLimit-Reset
A timestamp of the “next minute,” specified as seconds-since-epoch. I.e., at this time, your “X-RateLimit-Remaining” will reset to the value of “X-RateLimit-Limit” allowing more API requests.
JSON RESPONSE BODY
All non-authentication API calls will return a response with a JSON body (and content type “application/json”). These responses can all include the following keywords:
success
Value will be “1” on success; “0” on failure.
error_message
Appears only in error responses (where success=0). This is a plain text description of the error.
comment
Optional plain text message that can occur in successful requests (success=1). This is usually only present if the data keyword is omitted / not needed.
data
auth
Error responses for all API commands will have a consistent format. The HTTP Status code will be somewhere from 400 to 599, where the code number corresponds to the error type. The response body will be standard JSON with the “success” keyword set to “0” and the “error_message” keyword containing a plain text description of the reason for the failure.
Note that it is possible that in some cases the JSON error body would be missing; e.g. in situations where the error involved is unrelated to the API itself and so the API is not involved in the request and cannot return a standard error format. Examples of this could include cases 503 errors from a server being unavailable, bad gateway errors related to proxy load balancers, etc.
Note that Unicode and other characters can be embedded in double quoted strings in JSON response bodies. These should be properly parsed when the response body is converted from plain text JSON to an actual object in your code. Examples of common embedded characters include “\n” (for linefeed), “u0073” (for the letter “s” … to prevent the word “script” from showing up in the response, as that can trigger issues with filters). For example you may see in a raw response the string “de u0073cription”. Parsed, this becomes the string “description” – but the “s” is quoted in the raw response to limit the appearance of the raw text “script” … which could trigger content filters.
AUTHENTICATION & Calling the API
You can skip this section if you are using an SDK. This section provides detailed documentation on how to program your API clients to make API calls to the LuxSci API, how to authenticate, how to invalidate your API session, and how to make calls containing file attachments.
Here are the quick specifics you should know about all API calls:
- The API is accessed using REST-like calls.
- HTTPS must be used (TLS v1.2+) for all calls.
- UTF-8 encoded JSON is used as the data encapsulation format for both requests and responses.
- The content type “application/json” must be supplied with all JSON request bodies.
- You have limits on the number of requests/minute and requests/day that your API integration can perform. Plan accordingly.
- Successful requests will return an HTTP status code of 200-299; Failures will return a code of 400-599.
- File uploads are performed through multi-part form POST / PUT syntax with additional parameters sent via JSON.
Authentication Methods:
LuxSci’s API supports multiple authentication mechanisms to provide maximum flexibility. Each authentication mechanism is configured specifically for each AI Integration, so different integrations can use different mechanisms as appropriate for their needs. The support mechanisms are:
LuxSci Secure
- The default and most secure method. This includes message body signing and does not expose your API Secret in the individual API calls.
- While this is similar to API authentication methods supported by AWS and other secure systems, it is not a “standard.” LuxSci Secure requires either (a) using one of the provided SDKs or (b) implementing the authentication in your own code.
- SHA256 HMAC is used everywhere. These HMACs will always be HEX encoded. In the rest of the help, we will refer to them as just HMAC.
- All API calls, except for the authentication calls, must include cookies for the request HMAC signature.
- OAuth Client Credentials Flow (CCF) for account-level API Integrations
- OAuth Resource Owner Password Credentials Flow (ROPC) for user-level API Integrations
- Similar in security to “LuxSci Secure,” except that (a) API request bodies are not signed, (b) there is not an option for revoking authentication sessions, and (c) the Secret Key must be sent as part of the initial authentication request.
API Key
- Simple authentication mechanism that uses a specific request header for authentication
- Not very secure as (a) the Public Token and Secret Key are sent with every request, (b) there is no message body signing, and (c) there are no “sessions,” so one can not restrict session access to a specific IP address.
Basic Authentication
- Simple authentication mechanism that uses an HTTP Basic Authentication header.
- This has the same level of security as “API Key.”
AUTHENTICATION: OAuth 2.0
Account-scope API Integrations can use the “OAuth v2.0” Client Credentials Flow (CCF) standard authentication mechanism:
- Use the endpoint https://rest.luxsci.com/perl/api/v2/oauth to authenticate and retrieve the OAuth bearer token.
- Note, please refer to your API Integration settings for the proper hostname to use, as “rest.luxsci.com” is a default that may not apply in many cases.
- For OAuth 2.0, use:
- client_id = Public API Token
- client_secret = API Secret
- The OAuth authorization request expects the credentials to be sent in an HTTP “Authorization” header of type “Basic”.
- The OAuth resulting token is expected to be sent to requests in an HTTP “Authorization” header of type “Bearer”
- The OAuth 2.0 authentication mechanisms do not auto-renew your API token, so you will need to request a new token when the current one expires. This expiration time is given in the authentication response. By default, it is 15 minutes; however, it can be configured in some cases.
User-scope API integrations with OAuth use the OAuth 2.0 Resource Owner Password Credentials (ROPC) Flow. This works just like the CCF, described above, except that you put the username and password for the authenticating user in the JSON of the request body and change the grant type.
Once you have the OAuth token, it must be included in successive API requests using an Authorization header with a Bearer token (see below for an example).
The OAuth 2.o Token
The token provided by the OAuth 2.0 endpoint has a well-defined format: “client_id-session_id-epoch_seconds-signature”.
The client_id is the same as that used for authentication. You can use this to confirm that the OAuth token corresponds to your intended API Integration. epoch_seconds corresponds to when the token was generated, and this is used to determine when it expires.
Example OAuth 2.0 CCF Authentication Request
Note, in the following examples, we have truncated some of the long tokens with “…” to make them more concise.
POST https://rest.luxsci.com/perl/api/v2/oauth
Authorization: Basic VW8rRTJDT1NkS…XhIODdR
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials
HTTP/1.1 200 OK
Content-Type: application/json
{“token_type”:”Bearer”,”expires_in”:900,”access_token”:”Uo+E2COSdJ6POOA3ka8HQQMqK7sxgeuuX7+I3xaxSzk-22276-1743437973-42c4e7eb49e99448626eaa12ee2ef052c78b4104c4dcc3a4bf696903bcca82d4″}
Example OAuth 2.0 ROPC Authentication Request
POST https://rest.luxsci.com/perl/api/v2/oauth
Authorization: Basic VW8rRTJDT1…ZaGQrNDNSSmg3VnBBQTF3eXhIODdR
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials&username=test-user@domain.com&password=user-password
HTTP/1.1 200 OK
Content-Type: application/json
{“token_type”:”Bearer”,”expires_in”:900,”access_token”:”Uo+E2COSdJ6POOA3ka8HQQMqK7sxgeuuX7+I3xaxSzk-22276-1743437973-42c4e7eb49e99448626eaa12ee2ef052c78b4104c4dcc3a4bf696903bcca82d4″}
Example OAuth 2.0 Authenticated Request
GET https://rest.luxsci.com/perl/api/v2/account/1234567/users/report
Authorization: Bearer Uo+E2COSdJ6P…c4dcc3a4bf696903bcca82d4
AUTHENTICATION: API Key
Account-scope API Integrations can use the standard “API Key” authentication mechanism:
- Unlike OAuth and LuxSci Secure mechanisms, you do not authenticate and get a token back for use in API requests. Instead, you send an “X-API-Key: CODE” HTTP header with every request.
- CODE = client_id:client_secret
- client_id = Public API token
- client_secret = Secret Key for the API Integration
- These are joined together with a colon character in between.
For User-scope API Integrations:
- CODE = client_id:client_secret:username:BASE64(password)
- client_id = Public API token
- client_secret = Secret Key for the API Integration
- username = the login username of the user being authenticated
- BASE64(password) is the base64 encoding of that user’s password.
- These are joined together with a colon character in between each item.
Example API Key Authenticated API Request
GET https://rest.luxsci.com/perl/api/v2/account/1234567/users/report
X-API-Key: client_id:client_secret
AUTHENTICATION: Basic
Account-scope API Integrations can use the standard “Basic” authentication mechanism, which works a lot like the API Key mechanism.
- With each request, you send an “Authorization: Basic CODE” HTTP header with every request.
- CODE = Base64(client_id:client_secret)
- client_id = Public API token
- client_secret = Secret Key for the API Integration
- These are joined together with a colon character in between and encoded using base64.
For User-scope API Integrations:
- CODE = Base64(client_id:client_secret:username:password)
- client_id = Public API token
- client_secret = Secret Key for the API Integration
- username = the login username of the user being authenticated
- password is hat user’s password.
- These are joined together with a colon character in between each item, and the result is base64 encoded.
- Note, if you are using Basic Authentication in an SDK or Tool, you can enter “client_id:client_secret” in the provided “username” parameter and “username:password” in the provided “password” parameter to make it work in User scope.
Example Basic Authenticated API Request
GET https://rest.luxsci.com/perl/api/v2/account/1234567/users/report
Authorization: Basic VW8rRTJDT1N…F3eXhIODdR
AUTHENTICATION: LuxSci Secure
To use any API commands with the LuxSci Secure authentication mechanism, your API client must first authenticate and obtain an authentication code. This is similar to the OAuth process. This authentication code can then be used to make one or more calls to API functions. Your authentication “session” can also be revoked, immediately invalidating all authentication codes received for it (e.g., this is a “log out”).
To authenticate, you will need your API Token, API Key, and API Hostname. This API request differs from authenticated requests in that you do not need to send a Signature cookie, and the request is signed differently.
Note: with LuxSci Secure authentication, each successful authenticated request returns an “auth” keyword value pair in the JSON response body. The value of this pair is a new authentication token (with its session lifetime reset) that can be used for future calls. Using these tokens eliminates the need for re-authenticating unless there is a long time between successive requests.
Request Method
POST
Auth Cookie
None
Request URL
/perl/api/v2/auth
Request Query String
None
Request Body
Possible JSON object keywords:
- token
Required. Your API Token - date
Required. The current date and time. This can be in “epoch seconds” (e.g. “1426025141”) or in a standard date format that will be parsed and converted to epoch seconds. E.g., these formats are all OK: “Wed, 3 Mar 2015 13:12:15 -0400”
“Wed, 3 Mar 2015 13:12:15 GMT”
“2015-03-03 13:12:15 -0400”
“03-Mar-2015 13:12:15 GMT”
Your date and time (clock skew) must be no later than 15 minutes behind and no more than 1 minute ahead of our server time, or else the request will be rejected. - signature
Required. HMAC using your API Key as the HMAC key.
signature = HMAC( text_to_sign, API KEY) text_to_sign = token + “\n” + date + “\n”
If you are sending username and password information in this authentication request, then:
text_to_sign = token + “\n” + date + “\n” + user + “\n” + pass + “\n” - user
Optional. If you are authenticating into “user” scope with an explicit username and password, include the login email address of the user in question. E.g. “joe@domain.com”. This is the “LuxSci Secure User” pathway. - pass
Optional. If you are authenticating into “user” scope with an explicit username and password, include the plain text password for the user. This is the “LuxSci Secure User” pathway.
Success Response
Standard JSON response. No “data” keyword will be sent. See the “auth” keyword for your new authentication token.
EXAMPLE AUTHENTICATION REQUEST
POST https://rest.luxsci.com/perl/api/v2/auth
Content-Type: application/json
{ “token”: “pJsvioyq8LvtIthmqn8k1u4z0wbpnKwqotupx5DB1aM”, “date”:”1426025141″, “signature”: “1428c39c8d1893e4cab65181e6fe09ca36c3a18b5718c1df79b97f24c0c92c6e” }
EXAMPLE SUCCESS RESPONSE
HTTP/1.1 201 Created
Content-Type: application/json
Pragma: no-cache
Server: Apache
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 599
X-RateLimit-Reset: 1668889680
{“auth”:”965823916111409-1426025141-b3486705691ba0bd15e31292″ + “166e3494034c-748cb3fdfed0b9d456c647012763″,”success”:1}
AUTHENTICATED REQUESTS & SIGNATURE COOKIE
LuxSci Secure Authenticated API requests include all non-authentication requests. These work similarly to authentication requests described above, except that you must also send a cookie named “signature”. This cookie validates the request. The content of this cookie is defined as follows (note: we recommend using an SDK so that you do not need to code this up yourself):
signature: auth_code:signature_code
auth_code: a currently valid authorization code received from an Authorization API call, or from another successful recent API call.
signature_code: HMAC( text_to_sign, API Key)
text_to_sign: auth_code + “\n” + request_method + “\n” + request_path + “\n” + query_string + “\n” + request_body_hash + “\n”
request_method: the HTTP request method being used, in all upper case. E.g. “GET” or “POST” or “DELETE”
request_path: The portion of the request URL after the protocol and hostname, but before the ? and query string, if any. E.g. “/perl/api/v2/auth”
query_string: The portion of the request URL after the “?”. If you are not making a request that includes a query string, then you should treat this value as an empty string.
request_body_hash: If your request does not include a JSON request body, then you should treat this value as an empty string. Otherwise it is a SHA 256 Digest of the complete JSON request body:
request_body_hash: SHA_256_HEX( Trimmed JSON_Request_Body )
Trimmed JSON Request Body: the raw JSON Request Body content in the request with all leading and training white spaces removed (e.g. spaces, tabs, carriage returns, and line feeds before and after the actual JSON content).
For an example of this, see the next section: Authentication Revocation.
AUTHENTICATION REVOCATION
To revoke your LuxSci Secure authentication session and invalidate all authorization codes received, you need to send an authenticated API request as follows:
Request
Method DELETE
Auth Cookie
Required
Request URL
/perl/api/v2/auth
Request Query String
None
Request Body
None
Success Response
EXAMPLE: LUXSCI SECURE AUTHENTICATION FOLLOWED BY REVOCATION
Authentication request
POST https://rest.luxsci.com/perl/api/v2/auth
Content-Type: application/json
{“signature”:”67e2873a262d64bbdf06dacee633698683362df81b979c30b3f063dd1738c9a6″,”date”: “1426087957”,”token”:”pJsvioyq8LvtIthmqn8k1u4z0wbpnKwqotupx5DB1aM”}
Note: signature = HMAC( “pJsvioyq8LvtIthmqn8k1u4z0wbpnKwqotupx5DB1aM” + “\n” + “1426087957” + “\n”, API_KEY)
Success response
HTTP/1.1 201 Created
Content-Type: application/json
{“auth”:”151-1426087958-34ca90493592726104b237e98d8129fe8626f181e38f502fa2b99dc066e72298″,”success”:1}
Authentication Revocation
DELETE https://rest.luxsci.com/perl/api/v2/auth
Cookie: signature=151-1426087958-34ca90493592726104b237e98d8129fe8626f181e38f502fa2b9 9dc066e72298:fd66fc402b9c58f136105d768225a67dec4b8eeb756743bbca35c2caca0fd57f
Note: signature = “151-1426087958-34ca90493592726104b237e98d8129fe8626f181e38f502fa2b99dc066e72298” + “:” + signature_code
signature_code = HMAC(“151-1426087958-34ca90493592726104b237e98d8129fe8626f181e38f5 02fa2b99dc066e72298” + “\n” + “DELETE” + “\n” + “/perl/api/v2/auth” + “\n” + “” + “\n” + “” + “\n”, API_KEY)
Successful revocation
HTTP/1.1 200 OK
Content-Type: application/json
{“success”:1,”comment”:”Authentication session revoked.”}
REQUESTS WITH FILE UPLOAD
Some authenticated API requests allow you to include file attachments. When including files in your POST or PUT request, the HTTP syntax of the request is different: it uses a “multipart/form-data” content type instead of an “application/json” content type.
In particular:
- The request body must use a “multipart/form-data” content type instead of an “application/ json” content type.
- The JSON payload must be uploaded as one of the “parts.”
- The content type of that part should be “application/json”
- The “name” for the part must be “json”
- The filename should be “json.js”
- The content should be binary-encoded (not base64 or quoted printable) and be UTF-8.
- Each file uploaded will be additional, separate parts of the multipart upload
- The content type should be appropriate for the file
- The name for the part must be “files” (the name will be the same for all files uploaded in the same request).
- The filename for the part must be the filename of the file.
- The content should be binary-encoded (not base64 or quoted printable)
- In the JSON payload, you must include a top-level keyword named “attachments”. This is an array of JSON objects, one per uploaded file. These JSON objects contain the following keyword:
- “name” – This must match exactly the “filename” for one of the uploaded attachments. We do not current support uploading multiple attachments with the SAME name in the SAME request.
- “hash” – (For LuxSci Secure authentication only) This is a SHA256 hex-encoded digest of the uploaded file. We will check this hash against a hash of the file for validation before we process your request.
EXAMPLE OF A FILE UPLOAD REQUEST
Here is an example SecureLine Send request that includes a simple text file as an attachment and which is using LuxSci Secure authentication. The signature cookie is truncated to save space.
POST https://rest.luxsci.com/perl/api/v2/user/user@domain.com/email/compose/secureline/send
Content-Type: multipart/form-data; boundary=—————–LUXSCI-363789.496459765—
Cookie: signature=1623-1454003053-…a36d376c86313fbf65d8a
——————-LUXSCI-363789.496459765—
Content-Disposition: form-data; name=”json”; filename=”json.js”
Content-Type: application/json
{“attachments”:[{“hash”:”975867324207d82a1d1e01fa2b6e582907756e737aa7771d92b17609e41 bce16″,”name”:”test-attachment.txt”}],”from_address”:”bob@doctorbob.com”,”subject”:”SecureLine message test”,”no_tls_only”:1,”body”:”Message body”,”to”:[“user@test-domain.com”],”from_name”:”Dr. Bob”,”receipt”:1,”body_type”:”text”}
——————-LUXSCI-363789.496459765—
Content-Disposition: form-data; name=”files”; filename=”test-attachment.txt”
Content-Type: text/plain
File Content!!
——————-LUXSCI-363789.496459765—–
NOTE: If you are crafting these requests by hand, remember that you must use “\r\n” (i.e. char(13) char(10) ) as line terminators at the ends of the boundaries, the MIME headers, and blank spacer lines between MIME headers and your raw/binary attachment content.
HTTP RESPONSE CODES
The LuxSci REST API uses standard HTTP status codes to indicate the success or failure of requests. The codes commonly returned by the API and their meanings are below. In many cases, the API will also return a JSON object with a descriptive error string which provides more specific information.
- 200 — Success
- 201 — Success; Something was created
- 400 — Bad request. I.e., could be a validation error.
- 401 — Unauthorized. I.e., no permission to make the request.
- 403 — Forbidden. I.e., you have reached a service rate limit, or the action can not be completed for reasons other than permissions.
- 404 — Not found. I.e., you are attempting to delete an object that does not exist.
- 405 — Bad method. I.e., no such API endpoint.
- 408 — Timeout. The API request took too long to complete.
- 409 — Conflict. I.e, trying to make an object that already exists.
- 417 — Expectation Failed. Ensure that your request does not send an “Expect” HTTP header.
- 426 — Upgrade. The request can not be completed without your account first being upgraded.
- 429 — Too many. I.e., you already have too many objects of the specified type.
- 475 — Incomplete request. The back-end API server did not reeive the complete API request payload for some reason. This request should be re-tried, possibly after a short delay.
- 500 — Internal Error. Something went wrong on the server side. The error would be logged and visible to support.
- 501 — Not Implemented. The request has not yet been fully implemented.
- 503 — Service Unavailable. The request could not be completed because, for example, your server is down/could not be reached.