DUO API Reference¶
DUO is an email and SMS marketing platform. This document covers the REST API.
General Operation¶
DUO is designed such that the web application is a REST API client. Web application URLs are
API entrypoints that respond with human-machine interfaces when faced with a text/html
preference, or machine-parseable JSON when the Accept header requests application/json.
Authentication¶
Authentication requires a (username, password) pair. Each user account has one username and
any number of passwords. One password is the account password; the others belong to API Key
objects, which can be generated in the application.
- Use the account password for human interaction with DUO.
- Use API Keys for machine-to-machine integration — they can be revoked at any time.
Two authentication mechanisms¶
Basic HTTP Auth — Send the (username, password) pair as defined in
RFC 7617 on every request.
Note
Basic Auth sends credentials in cleartext in the HTTP channel, but all communication is SSL-encrypted (HTTPS), so there is no security concern as long as credentials are not included in the request URL.
Session-based authentication — The mechanism used by the web application. Submit a POST
to /login/, receive a session token, then send it as a cookie named sergiosgc_auth on every
request. Terminate with a POST to /logout/.
Response Envelope¶
Every JSON response is a dictionary with two keys:
| Key | Type | Description |
|---|---|---|
success |
boolean | true if the operation succeeded |
data |
object | Actual response data, dependent on the endpoint |
HTTP 200 is returned when application code executed correctly. If the operation fails for
application-level reasons, the JSON response will show success: false.
When success is false, data will contain a dictionary with at least an "error" key
containing a textual description of the error.