Support

Support Ticket

You can create a Support Ticket within your environment portal under "Support" -> "Support Desk" and completing the short form to open a new ticket.

Email

If you have any questions or feedback about using the Rixon API, please email us at techops@rixontechnology.com.

If you are running into an API error, please also include the request trace ID when emailing us. You can find the request trace ID in the x-requestid API response header.

Remember: Before communicating with Rixon Technology, check that you're not sending any sensitive information such as headers or requests with tokens and authorization information.

Service Uptime Monitoring

https://status.rixontechnology.com/




Guides

Versioning

Breaking changes can be disruptive and we take versioning very seriously. If we require sunsetting a legacy endpoint, we'll notify you with sufficient lead time to migrate. We recommend implementing against the latest endpoints documented in the Rixon API.

Breaking changes

We don't consider the following types of changes as breaking changes, so please don't be worried when you see them:

  • New endpoints
  • New read-only or optional fields
  • Endpoints or fields marked as deprecated
  • New enum constants

Note: Your code should be able to handle new types of responses. For example, please ensure that you design your code to handle unknown enum types and new fields in responses.


API Error Handling

Rixon uses HTTP response status codes to indicate the success or failure of your API requests. If your request fails, Rixon returns an error using the appropriate status code.

In general, there are 3 status code ranges you can expect:

  • 2xx : Success status codes confirm that your request worked as expected.
  • 4xx : Error status codes indicate an error because of the information provided (e.g., a required parameter was omitted).
  • 5xx : Error status codes are rare and indicate an error with Rixon's servers.

All Rixon Technology API endpoints include an errors object in their response body when the request fails. It will contain a type, message, and optional code. For example:

HTTP/1.1 400 Bad Request


{
  "errors": {
    "code": [
      "[ErrorCode]"
    ],
    "Validation": [
      "[Field] is Invalid"
    ]
  },
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "traceId": "00-4d6e036689bbc3608e2b0c16eb968b16-671fc005fc4a712c-00"
}
                                

HTTP/1.1 404 Not Found


{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
  "title": "Not Found",
  "status": 404,
  "traceId": "00-1d7bd1f5dc226634fd44a79bcc860768-712b243be6649137-00"
}
                                

HTTP/1.1 403 Forbidden


{
  "errors": "[ErrorCode]",
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.4",
  "title": "Forbidden",
  "status": 403,
  "traceId": "00-000aed33eade6918c465a7dc5e576403-f8fbe708326c8359-00"
}
                                

Common errors and fixes

Status code
Endpoint
Error Message
Fix
400 Any POST with free form text input [Field name] is invalid Free form text fields, display names, etc. can only accept ASCII characters.
401 Any endpoint Unauthorized; Expired token For Portal APIs, Generate a new JWT token. For Tokenization APIs, generate a new SessionToken.
403 Any endpoint Forbidden For Portal APIs, Generate a new JWT token. For Tokenization APIs, generate a new SessionToken.

Request Correlation

All requests are tagged with several unique identifiers. The response of every request contains a header as x-requestid which can be used to trace the request throughout our technology stack. When triaging and troubleshooting, making a note of this value will expedite analysis.


Pretty Responses

By default, all APIs which return json, return a minified/compressed json object to optimize transmission of data. You can optionally toggle that a request return "pretty" formatted/indented json object. To do this, either add "?pretty" as a query string parameter or include the HTTP header or x-printpretty in your API request.


Rate limits

The Rixon API employs rate limits as a safeguard against abuse and to ensure API stability. Per Client ID, Per IP Address, and Per account. Specific rate limits are defined internally on each environment therefore you should contact your customer success representative to adjust your rate limits. By default:

  • Up to 600 requests in 1 second.
  • Up to 10,000,000 transfers in 24 hours.

Exceeding a rate limit will result in an HTTP 429 (too many requests) response. Rate limits may be reduced further to prevent abuse or ensure system reliability. Rixon Technology may reduce limits to prevent abuse or ensure system reliability. If you require higher rate limits for a high volume application, please contact support.

Rate Limit Response Headers

  • x-rate-limit-limit - Defines the most restrictive internal limit rule that is being measured
  • x-rate-limit-remaining - The number of requests allowed until. all requests will be rejected/denied
  • x-rate-limit-reset - The datetime when the limit and counters will be reset

Handling rate limits gracefully

If you encounter rate limits, there may be a workaround depending on your circumstance.

If your rate limiting is due to frequent polling of certain endpoints, you may be able to leverage the Webhooks Feature to instead receive real time notifications of important events. If we do not yet support a webhook that you require, let us know.

If webhooks are not a viable option to reduce call volume, you can watch for 429 status codes and implement a retry mechanism. We recommend using an exponential backoff schedule with some randomness to avoid the thundering herd problem.

Another option is to throttle traffic to Rixon more broadly per Client ID rather than for individual requests. A token bucket algorithm implemented per Client ID and optionally also against a specific type of rate limit (as listed at the top of this page) may help you mitigate or avoid the effect of rate limits on your application.



Quickstart

This guide will help you get up and running making your first Rixon Tokenization API call in just a few minutes.

This guide assumes you are a Rixon customer with admin access to your portal.

1. Generate your credentials

Before starting the process of data protection, you need to determine the type of data that requires protection. After that, you should define the data format and access privileges. To protect each type of data, you need to create a token definition that provides instructions to the Rixon platform on how to handle that specific data.


Setting Up API Keys

Navigate

From the sidenav in the portal, go to Account→Configurations→API Keys.

Service API Key Creation

In order to securely communicate with Rixon’s tokenization & data protection API’s you will need to create a Service API key. Your account may already have an autogenerated API key created. Your API key(s) should be stored securely and not shared since these keys are used to authenticate to Rixon’s data protection functionality.

In order to use Rixon to secure your sensitive data, we need to prepare Rixon to accept and protect your data. In order to configure Rixon you will need a portal user with at least the "AccountAdmin" role assigned or higher. This role will allow you to navigate to Account→Configurations→API Keys.

An autogenerated API key may already exist. You are safe to use this autogenerated API Key. If you'd like to create a new Key yourself, locate the section labeled “Add an API Key.” Enter a name for the key in the title field, and enter an expiration date. API Keys are not usable after they expire and should be rotated frequently. Click “Issue New API Key” and your key will appear above under the section labeled “Your Existing API Keys.”


Creating Token Definitions

Navigate

From the sidenav in the portal go to Account→Configurations→Token Definitions.

In the header of the token table, click “Create New” to access the token creation wizard.

Token Definition Creation

The token creation wizard will walk you through steps to create your token definition(s). You can accept the defaults or read the descriptions of each option to customize how your data is handled. Make sure to repeat the process of creating a token definition for each type of data you wish to protect.


Configuring Security Policies

Navigate

From the sidenav in the portal go to Account→Configurations→Security Policies.

Security Policy Configuration

Security policies defined in Rixon will define the access controls that will be enforced on API requests for tokenization.

Locate the “Security Policy Table” and click the “Create New” button. Read the description of each option and fill out the required fields. Customize each option as necessary or accept the defaults. Make sure under access controls you give your security policy the appropriate API operation permissions for your token definition.

2. Make your first API Call

With your API Key and Security Policy, you can now make an CreateSession API call. For this example, we'll hit the CreateSession endpoint which authenticates and authorizes, yielding a Session Token.

Below is an example.

curl


curl -X 'POST' \
  'https://<YOUR_ACCOUNT_DOMAIN>/api/services/evtservice/createsession' \
  -H 'Content-Type: application/json' \
  -d '{
  "apiKey": "<YOUR_API_KEY>",
  "policy": "<THE_POLICY_NAME>",
  "policyPassword": "<THE_POLICY_PASSWORD>"
}''
                                    

With the Session Token, you can now make a Tokenization API call. For this example, we'll hit the Tokenize endpoint which simply tokenizes a single value with the tokenization engine parameters defined in the Token Definition.

curl


curl -X 'POST' \
  'https://<YOUR_ACCOUNT_DOMAIN>/api/services/evtservice/tokenize' \
  -H 'Content-Type: application/json' \
  -d '{
  "sessionToken": "<THE_SESSION_TOKEN_FROM_PREVIOUS_REQUEST>",
  "tokenName": "<THE_TOKENDEF_NAME>",
  "value": "MySensitiveValue"
}''
                                    

Next steps

Congratulations, you've protected your data with tokenization! You're ready to dive deeper.

Reading through the rest of the guides will familiarize you with important Rixon API conventions and implementation concerns. The API references will give you a better understanding of what functionality is included in each API and whether they will meet the needs of your use case. If you need help, see our support page. Happy developing!



Rixon API Overview

Rixon Technology is the first fully unified security platform — with tokenization apis and services. Rixon makes it easy for teams and technology to be secured, all in one place. Using the Rixon API, you can security your data.

Rixon APIs use the REST architecture, are defined using the OpenAPI specification and use standard HTTP response codes and verbs. All APIs accept and return JSON and require HTTPS.

Explore our guides and review our API documentation to see how you can integrate with Rixon Technology.



Rixon Query Language

Querying your database is an essential part of any application. Our apis use plain URLs with simple parameters and JSON documents to query your database. In this section we will give you plenty of REST API examples using MongoDB like query syntax.

Query language

Database queries are created as valid JSON documents. A query object consists of fields and operators that make up a complete query. Please note that query fields are case sensitive.

A simple query example:

https://<your_env_domain>/rest/customers?q={"status": "GOLD"}

Which is the same as asking the database: fetch all records with status GOLD

Please note that maximum 1000 records are returns from any query unless the $max parameter is specified.

Simple queries

Match a single field (find Joe):

https://<your_env_domain>/rest/people?q={"name": "Joe"}

Match multiple fields (find Joe who's 17):

https://<your_env_domain>/rest/people?q={"name": "Joe", "age": 17}

In addition to query simple fields, you can use special operators to perform more advanced queries.

Logic operators

$not operator

Return documents not matching the query.

https://<your_env_domain>/rest/people?q={"name" : {"$not" : "Joe"}}

$in operator

Return documents matching any values.

https://<your_env_domain>/rest/people?q={"name" : {"$in" : ["Joe", "Jane", "Donald"]}}

$nin operator

Return documents not matching any of the values.

https://<your_env_domain>/rest/people?q={"name" : {"$nin" : ["Joe", "Jane", "Donald"]}}

$regex operator

Match a regular expression against field.

https://<your_env_domain>/rest/people?q={"name" : {"$regex" : ".Joe*"}}

$or operator

Return documents that matches one or the other field.

https://<your_env_domain>/rest/people?q={"$or": [{"name": "Jane"}, {"name": "Donald"}]}

$and operator

Return documents both fields.

https://<your_env_domain>/rest/people?q={"$and": [{"name": "Jane"}, {"last-name": "Cassidy"}]}

Logical operators overview

OperatorDescriptionExample
$notNegation logical operator{"field" : {"$not" : val}}
$inMatch any value in array{"field" : {"$in" : [value1, value2, ...]}}
$ninNot match any value in array{"field" : {"$nin" : [value1, value2, ...]}}
$regexMatch field{"field" : {"$regex" : ".*"}}
$orLogical operator{"$or": [{"status": "GOLD"}, {"status": "SILVER"}]}
$andLogical operator{"$and": [{"status": "GOLD"}, {"sales": 1000}]}

Conditional operators

$gt operator

Return documents that matches each field value greater than numeric value.

https://<your_env_domain>/rest/people?q={"salary": {"$gt": 10000}}

$gte operator

Return documents that matches each field value greater than or equal to numeric value.

https://<your_env_domain>/rest/people?q={"salary": {"$gte": 10000}}

$lt operator

Return documents that matches each field value less than numeric value.

https://<your_env_domain>/rest/people?q={"salary": {"$lt": 10000}}

$lte operator

Return documents that matches each field value less than or equal to numeric value.

https://<your_env_domain>/rest/people?q={"salary": {"$lte": 10000}}

$bt operator

Return documents that matches each field value between two numeric values.

https://<your_env_domain>/rest/people?q={"salary": {"$bt": [5000, 7500]}}

$exists operator

Return documents that matches each field with a value.

https://<your_env_domain>/rest/people?q={"field": {"$exists": true}}

$exists (sub array) operator

Return documents that matches each sub field with any value.

https://<your_env_domain>/rest/people?q={"field.0": {"$exists": true}}

$elemMatch operator

Return documents that matches at least one of the elements in an array field.

https://<your_env_domain>/rest/people?q={"contact":{"$elemMatch":{"name":"Anderson", age:35}}}

$distinct operator

Return array of unique values from matching fields.

https://<your_env_domain>/rest/people?q={"$distinct": "age"}&sort=age

Example output:
[
 "18",
 "19",
 "20",
 "21",
 "22",
 "23",
 "24",
 "25",
 "26"
 ]

Conditional operators overview

OperatorDescriptionExample
$gt>{"salary": {"$gt": 10000}}
$gte>={"salary": {"$gte": 10000}}
$lt<{"salary": {"$lt": 10000}}
$lte<={"salary": {"$lte": 10000}}
$bt>= value <={"salary": {"$bt": [5000, 7500]}}
$existsCheck if field exists{"field": {"$exists": true|false}}
$exists (array)Check if array field exists or is empty{"field.0": {"$exists": true|false}}
$elemMatchArray element matching{"contact":{"$elemMatch":{"name":"Anderson", age:35}}}
$distinctArray with unique element values{"$distinct": "name"}

Date operator

Querying based on dates are done using the $date operator combined with ISO date strings. For example:

// between two dates
{"_changed":{"$gt":{"$date":"2016-08-01"},"$lt":{"$date":"2016-08-05"}}}

Dynamic date variables

To enable more dynamic queries using the $date operator, like "get all records this month", we have added a number of predefined date variables.

// older than the time just now
{"startat":{"$lt":{"$date":"$now"}}}
NameDescription
$nowjust now
$currentMinutestart of last minute
$currentHourstart of last hour
$currentDatestart of current day
$todaystart of current day
$tomorrowstart of next day
$yesterdaystart of day before
$currentWeekstart of this week (sunday)
$currentMonthstart of this month
$currentYearstart of this year
$nextWeekstart of next week (sunday)
$nextMonthstart of next month
$nextYearstart of next year

We also support MomentJS. Check out their docs and compose the date variable like this:

{"startat":{"$gt":{"$date":"$moment.endOf.hour"}}}
{"startat":{"$gt":{"$date":"$moment.subtract.3.days"}}}
{"startat":{"$gt":{"$date":"$moment.subtract.3.hours"},"$lt":{"$date":"$moment.add.3.hours"}}}
{"startat":{"$gt":{"$date":"$moment.startOf.year"},"$lt":{"$date":"$moment.endOf.year"}}}

Sort operator

The $orderbyoperator lets you sort the result from a query. You can sort on single or multiple fields within the same query. We use the URL parameter hint h={..} to specify sorting.

E.g. query all records from peopleand sort the result set by name in ascending order, and then by age in descending order.

https://<your_env_domain>/rest/people?q={}&h={"$orderby": {"name": 1, "age": -1}}

URL Parameters overview

As part of the REST API, restdb.io has a number of parameters that we can use. They are added to the REST URLs as query parameters shown below:

https://<db-name>.restdb.io/rest/<collection>[.<format>]?q={}&h={}&...

The following table shows all valid URL parameters to a database REST endpoint:

ParameterDescription
qDatabase query
Example: GET "Karen Johnston, age 39":
https://<your_env_domain>/rest/people?q={"firstname":"Karen", "lastname":"Johnson", age: 39}
hQuery hints to specify: fields, max, skip and orderby. Aggregation parameters can also be specified as hints, read more here
Example: Return title, only 10 records, forward to the 5.th item and sort result set by the body field:
https://<your_env_domain>/rest/people?q={}&h={"$fields":{"title":1},"$max":10,"$skip":5,"$orderby":{"body":1}}
filterPerforms a text search and retrieves all matching documents
Example: https://<your_env_domain>/rest/people?q={}&filter=johnson
sortSpecifies which field(s) should be used to sort the result. You can add multiple fields by simply adding another sort parameter. Default sort=_id
Example: https://<your_env_domain>/rest/people?q={}&sort=lastname
dirSort direction. Allowed values are 1 (ascending) and -1 (descending). Used together with sort. Multiple dir parameters can be used in conjunction with sort.
Example: https://<your_env_domain>/rest/people?q={}&dir=-1
skipWhere to start in the result set. Used for paging.
Example: https://<your_env_domain>/rest/people?skip=100
maxMaximum number of records retrieved. Default is 1000.
Example: https://<your_env_domain>/rest/people?max=20
totals&totals=true returns an object with both data and total count. Totals equals to max parameter or default 1000
Example: output from query ->{data: [ … ], totals: { total: 100, count: 40, skip: 0, max: 1000}}
totals and count&totals=true&count=true returns an object with no data and just the total count
Example: output from query -> {data: [], totals: { count: 42}}
groupbyGroup output from query by a field
Example: https://<your_env_domain>/rest/people?groupby=gender
aggregatePerform aggregation function on data groups. Useful together with groupby parameter. Avaliable functions; SUM, AVG, MIN, MAX and COUNT Docs
Example: https://<your_env_domain>/rest/people?groupby=gender&aggregate=SUM:weight&aggregate=AVG:age
formatOutput format from request. .html returns a standard markup for all fields. .js (Javascript) returns a script that can be included in a web page for search engine indexing. .json standard JSON format
Example: https://<your_env_domain>/rest/people.html
apikeyA valid apikey, full access key or a CORS enabled key
Example: https://<your_env_domain>/rest/people?&apikey=4321fd234f0876....
Not recommended for production. Use header field x-apikey instead
idtolinkInserts canonical URLs for image references and object references
Example: https://<your_env_domain>/rest/people?idtolink=true
flattenUsed together with idtolink. Extract links as properties on root object
Example: https://<your_env_domain>/rest/people?flatten=true
referencedbyReturn all items that refers to a record. Requires a record _id in the query or path
Example: https://<your_env_domain>/rest/people/56011150e1321c7300000001?referencedby=true
fetchmediadataReplace media ID's with a full record from the media archive
Example: https://<your_env_domain>/rest/people?fetchmediadata=true
fetchchildrenInsert records from parent-child relation on parent record
Example: https://<your_env_domain>/rest/company?fetchchildren=true

Query examples

The following table shows some examples on how to query:

QuerySyntax
Get items that have status = "pro" and title="yay"q={"status”:"pro","title”:”yay"}
Get items that have status = "pro" or "basic"q={"$or":[{"status”:"pro"},{“status”:”basic"}]}
Get items that have status like "basic" (regular expression)q={"status":{"$regex”: ”basic"}}
Get all items updated within date interval (use ISOString or dates that can be converted to ISOString)q={"_changed":{"$gt":{"$date":"2016-08-01"},"$lt":{"$date":"2016-08-05"}}}
Get items created this month, i.e. newer than 1.st 00:00 AM this monthq={"_created":{"$gt":{"$date":"$currentMonth"}}}
Get all items with a score > 900, and group them by categoryh={"$groupby":["category"]}&q={"score":{"$gt": 900}}

Comprehensive code examples for various languages

SQL to NoSQL mapping

The following table shows how traditional SQL statements are expressed as RestDB Queries.

SQLRestDB
SELECT * FROM usershttps://<your_env_domain>/rest/users?q={}
SELECT id, user_id, status FROM users/rest/users?q={}&h={"$fields": {"user_id": 1, "status": 1} }
SELECT * FROM users WHERE status = "A"/rest/users?q={ "status": "A" }
SELECT * FROM users WHERE status != "A"/rest/users?q={"status":{"$not":"A"}}
SELECT * FROM users WHERE status = "A" AND age = 50/rest/users?q={ "status": "A", "age": 50 }
SELECT * FROM users WHERE status = "A" OR age = 50/rest/users?q={ "$or": [ { "status": "A" } ,{ "age": 50 } ] }
SELECT * FROM users WHERE age > 25/rest/users?q={ "age": { "$gt": 25 } }
SELECT * FROM users WHERE age < 25/rest/users?q={ "age": { "$lt": 25 } }
SELECT * FROM users WHERE age > 25 AND age <= 50/rest/users?q={ "age": { "$gt": 25, "$lte": 50 } }
SELECT * FROM users WHERE user_id like "%bc%"/rest/users?q={ "user_id": {"$regex" :"bc"}}
SELECT * FROM users WHERE user_id like "bc%"/rest/users?q={ "user_id": {"$regex" :"^bc"}}
SELECT * FROM users WHERE status = "A" ORDER BY user_id ASC/rest/users?q={ "status": "A" }&sort=user_id&dir=1
SELECT * FROM users WHERE status = "A" ORDER BY user_id DESC/rest/users?q={ "status": "A" }&sort=user_id&dir=-1
SELECT COUNT(*) FROM users/rest/users?q={}&h={"$aggregate":["COUNT:"]}
SELECT COUNT(*) FROM users WHERE age > 30/rest/users?q={"age":{"$gt": 30}}&h={"$aggregate":["COUNT:"]}
SELECT * FROM users LIMIT 1/rest/users?q={}&max=1
SELECT * FROM users LIMIT 5 SKIP 10/rest/users?q={}&max=5&skip=10