API Reference Manual

Overview

API allows you to control all features of c0x0.com in a programistic way. Full access to this features is available for Developer subscribers.

There is special-purpose open API available for all users with limitted functionality for browser extension - or any other app that one want to develop. This API is called XPI and details are below.

API endpoint is located at https://api.c0x0.com/VERSION/. Current version is v1. See below examples how to construct proper calls.

Response Codes
In general we are following RESTfull recommendations regarding HTTP response codes. To keep things short: HTTP 200 (OK) always means action on API was executed and result is correct - responses are in JSON format.
Error codes are not JSON formated and descriptive text of the error is attached in the message, example:
curl -I -H "Authorization: Bearer $token" -X POST https://api.c0x0.com/v1/delete-domain/c0x0.com
Domain do not exist or not en owner

curl -I -H "Authorization: Bearer $token" -X POST https://api.c0x0.com/v1/delete-domain/c0x0.com
HTTP/1.1 400 Bad Request
Server: nginx
Date: Wed, 22 May 2019 13:58:44 GMT
Content-Type: text/plain; charset=utf-8
Content-Length: 36
Connection: keep-alive
X-Content-Type-Options: nosniff

General Access XPI API

XPI endpint is: https://api.c0x0.com/xpi/
See our browser extension source code for example usage in JavaScript.

Create Alias with Tag

Creates new alias and attaches tag/description to it. Tag is optional.
- parm1: FQDN of the service
- parm2: base64url description of the alias (this is optional parameter)

POST /xpi/create-alias-xpi/{parm1}/{parm2}
curl -H "Authorization: Bearer $token" -X POST https://api.c0x0.com/xpi/create-alias-xpi/example.com/bXlwYWdldGVzdCA=
{ "result": "ttq27dgc0tebn9b@c0x0.com" }

List Aliases with given scope

Return aliases used with given scope
- parm1: scope need to be FQDN

GET /xpi/list-aliases/{parm1}
curl -H "Authorization: Bearer $token" -X GET https://api.c0x0.com/xpi/list-aliases/example.com
[
  {
    "alias_id": "3548026197058423",
    "alias": "zek6r5ekz4k5p5r@c0x0.com",
    "dest": "john@doe.com",
    "tag": "LLoyd Bank",
    "status": "active",
    "scope": "example.com"
  },
  {
    "alias_id": "27691808423",
    "alias": "rkw0335sef04y00@c0x0.com",
    "dest": "john@doe.com",
    "tag": "Facebook",
    "status": "active",
    "scope": "example.com"
  },
  {
    "alias_id": "3307827691808423",
    "alias": "cpfeup49chp4gye@c0x0.com",
    "dest": "john@doe.com",
    "tag": "eBay",
    "status": "active",
    "scope": "example.com"
  },
]

Developer API

Endpint is: https://api.c0x0.com/v1/

Renew JWT token

Renew JWT token. Tokens expiry every 7 days. It is good practice to renew them when possible

GET /v1/renew-token
curl -H "Authorization: Bearer $token" -X GET https://api.c0x0.com/v1/renew-token
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

Create Alias

Create alias for given endpoint
- parm1: confirmed endpoint e-mail address

POST /v1/create-alias/{parm1}
curl -H "Authorization: Bearer $token" -X POST https://api.c0x0.com/v1/create-alias/john@doe.com | jq '.'
{
  "result": "ttq27dgc0tebn9b@c0x0.com"
}

Create Alias in Custom Domain

Create alias for given endpoint in hosted custom domain
-parm1: confirmed endpoint e-mail address
-parm2: valid and verified domain name

POST /v1/create-alias/{parm1}/{parm2}
curl -H "Authorization: Bearer $token" -X POST https://api.c0x0.com/v1/create-alias/john@doe.com/example.com | jq '.'
{
  "result": "ttq27dgc0tebn9b@example.com"
}

Create Alias in Custom Domain with Custom Alias

Create alias for given endpoint in hosted domain with custom alias (non-random)
-parm1: confirmed endpoint e-mail address
-parm2: valid and verified domain name
-parm3: valid alias that forms valid e-mail address

POST /v1/create-alias/{parm1}/{parm2}/{parm3}
curl -H "Authorization: Bearer $token" -X POST https://api.c0x0.com/v1/create-alias/john@doe.com/example.com/johnny | jq '.'
{
  "result": "johnny@example.com"
}

Set Tag on alias

Adds tag or name to previously created alias
-parm1: base64url encoded tag name
-parm2: alias

POST /v1/set-tag/{parm1}/{parm2}
curl -H "Authorization: Bearer $token" -X POST https://api.c0x0.com/v1/set-tag/bmFtZSB0YWc/ttq27dgc0tebn9b@c0x0.com | jq '.'
{
  "result": "ok"
}

Enable or Disable given alias

Enables or Disabled given alias on backend. Aliases in disabled state drop incomming mail at protocol level
-parm1: alias
-parm2: one of actions: [active|inactive]

POST /v1/set-alias/{parm1}/{parm2}
curl -H "Authorization: Bearer $token" -X POST https://api.c0x0.com/v1/set-alias/ttq27dgc0tebn9b@c0x0.com/inactive | jq '.'
{
  "result":"Alias deactivated"
}

List aliases

Lists aliases and their metadata as json payload

GET /v1/list-aliases
curl -H "Authorization: Bearer $token" -X GET https://api.c0x0.com/v1/list-aliases | jq '.'
 [
  {
    "alias_id": "3548026197058423",
    "alias": "zek6r5ekz4k5p5r@c0x0.com",
    "dest": "john@doe.com",
    "tag": "LLoyd Bank",
    "status": "active"
  },
  {
    "alias_id": "27691808423",
    "alias": "rkw0335sef04y00@c0x0.com",
    "dest": "john@doe.com",
    "tag": "Facebook",
    "status": "active"
  },
  {
    "alias_id": "3307827691808423",
    "alias": "cpfeup49chp4gye@c0x0.com",
    "dest": "john@doe.com",
    "tag": "eBay",
    "status": "active"
  },
]

Delete Alias

This call delete alias. First you need to get AliasID from call describe-alias, see below
- parm1: alias id

POST /v1/delete-alias/{parm1}
curl -H "Authorization: Bearer $token" -X POST https://api.c0x0.com/v1/delete-alias/98540593194375 | jq '.'
{
  "result":"Alias Deleted"
}

Describe Alias

Shows alias metadata
- parm1: alias

GET /v1/describe-alias/{parm1}
curl -H "Authorization: Bearer $token" -X GET https://api.c0x0.com/v1/describe-alias/ttq27dgc0tebn9b@c0x0.com | jq '.'
[
  {
    "alias_id": "98540593194375",
    "tag_name": "name tag",
    "destination": "john@doe.com"
  }
]

Get Account Status

Shows account status

GET /v1/get-user-status
curl -H "Authorization: Bearer $token" -X GET https://api.c0x0.com/v1/get-user-status | jq '.'
{
  "result":"active"
}

Get User Subscription

Shows user current subscription level

GET /v1/get-user-subscription
curl -H "Authorization: Bearer $token" -X GET https://api.c0x0.com/v1/get-user-subscription | jq '.'
{
  "result":"4"
}

Update Endpoint

Updates endpoint e-mail address. Due to sensitivity of this call, it is disabled by default.
To enable it go to account settings. Endpoint first need to be confirmed, see below.
- parm1: alias
- parm1: valid and confirmed endpoint e-mail address

POST /v1/update-endpoint/{parm1}/{parm2}
curl -H "Authorization: Bearer $token" -X POST https://api.c0x0.com/v1/update-endpoint/tns4zdd5t6wz4gs@c0x0.com/johnthesecond@doe.com | jq '.'
{
  "result":"ok"
}

Validate Endpoint

Add endpoint e-mail address to validation queue. Confirmation mail is sent to the address.
Confirmation code need to be then used below to verify ownership of the address
- parm1: e-mail address

POST /v1/validate-endpoint/{parm1}
curl -H "Authorization: Bearer $token" -X POST https://api.c0x0.com/v1/validate-endpoint/johnthesecond@doe.com | jq '.'
{
  "result":"Confirmation Code Sent"
}

Confirm Endpoint

Performs validation of the given endpoint e-mail address. Code first need to be generated by validate-endpoint call.
- parm1: e-mail address
- parm1: confirmation code

POST /v1/confirm-endpoint/{parm1}/{parm2}
curl -H "Authorization: Bearer $token" -X POST https://api.c0x0.com/v1/confirm-endpoint/johnthesecond@doe.com/5500975233917520 | jq '.'
{
  "result":"Confirmed"
}

Delete Endpoint

Delete endpoint and all it's related aliases
- parm1: endpoint e-mail address

POST /v1/delete-endpoint/{parm1}
curl -H "Authorization: Bearer $token" -X POST https://api.c0x0.com/v1/delete-endpoint/johnthesecond@doe.com | jq '.'
{
  "result":"Deleted"
}

List Endpoints

Lists all available endpoints and their statuses

GET /v1/list-endpoints
curl -H "Authorization: Bearer $token" -X GET https://api.c0x0.com/v1/list-endpoints | jq '.'
[
  {
    "endpoint": "john@doe.com",
    "status": "johnthesecond@doe.com"
  },
  {
    "endpoint": "john@doe.com",
    "status": "confirmed"
  }
]

Add Domain

Add custom domain for aliases. Domain need to be confirmed. Call returns formated DNS RR in bind format.
- parm1: fqdn

POST /v1/add-domain/{parm1}
curl -H "Authorization: Bearer $token" -X POST https://api.c0x0.com/v1/add-domain/example.com | jq '.'
{
  "result": "_c0-token.example.com. IN TXT a9em07jp6qb8"
}

Confirm Domain

Triggers backend check if domain is valid (checks for TXT record, see above)
- parm1: fqdn

POST /v1/confirm-domain/{parm1}
curl -H "Authorization: Bearer $token" -X POST https://api.c0x0.com/v1/confirm-domain/example.com | jq '.'
{
  "result": "Domain Confirmed"
}

List Domains

List domains and their metadata

GET /v1/list-domains
curl -H "Authorization: Bearer $token" -X GET https://api.c0x0.com/v1/list-domains | jq '.'
[
  {
    "domain": "example2.com",
    "status": "confirmed",
    "v_code": "63wg0txe0y2k"
  },
  {
    "domain": "example.com",
    "status": "pending",
    "v_code": "a9em07jp6qb8"
  }
]

Delete Domain

Delete domain and all aliases related
- parm1: fqdn

POST /v1/delete-domain/{parm1}
curl -H "Authorization: Bearer $token" -X POST https://api.c0x0.com/v1/delete-domain/example.com | jq '.'
{
  "result": "Deleted"
}