Authentication

You'll need to authenticate your requests to access endpoints in the CollateralXP API. This guide will examine how authentication works with an API key and the X-Api-Email header. Besides, it'll also teach you how to use the /me endpoint to seamlessly invite new users.

API key

To request an API key, please contact us at support@collateralxp.com. You can provide the API key in the header or as a query parameter, look at the examples below.

Here is how to authenticate with an API key in the header:

curl https://staging.app.collateralxp.com/api/v1/property_types \
  -H "Accept: application/json" \
  -H "X-Api-Key: {api_key}"

And in the query parameter:

curl https://staging.app.collateralxp.com/api/v1/property_types?api_key={api_key}

Always keep your API key safe and inactivate it if you suspect it has been compromised.

/me endpoint and X-Api-Email header

The API keys are a user-level authentication, and we understand that the system you are integrating into CollateralXP could have many users. To make your life easier, we enable you to invite new users through /me and to authenticate on the users' behalf with X-Api-Email.

When you post to /me, you can provide the X-Api-Email, X-Api-First-Name, and X-Api-Last-Name headers. If there isn't a user with the provided email, we'll create a new user and send them an invitation email.

curl -X https://staging.app.collateralxp.com/api/v1/me \
  -H "Accept: application/json" \
  -H "X-Api-Key: {api_key}" \
  -H "X-Api-Email: john@doe.com" \
  -H "X-Api-First-Name: John" \
  -H "X-Api-Last-Name: Doe"

This will seamlessly invite the john@doe.com user.

Afterwards, you can authenticate on the user's behalf with the X-Api-Email header:

curl https://staging.app.collateralxp.com/api/v1/property_types \
  -H "Accept: application/json" \
  -H "X-Api-Key: {api_key}" \
  -H "X-Api-Email: john@doe.com"