API Keys Management

API Keys provide a simple and efficient approach to API authentication, allowing direct control over access without the need for complex renewal flows as required by JWTs. With API Keys, issuing, replacing, and revoking keys is straightforward, making access management faster and more secure.

Avenia API strongly encourages the use of API Keys in your integration/workflow.

The API Key is directly linked to access (click here to learn more about access management), with a maximum of 5 API Keys per access!

Avenia API Support

warning

To register your API Key, you must have TOTP MFA activated. Click here to learn how to set this up!

Avenia API supports RSA, ECDSA, and Ed25519 cryptographic keys for API Key authentication (secure methods of protection and identity verification, allowing you to securely authenticate and use the Avenia API API).

Avenia API also supports CIDR (Classless Inter-Domain Routing), which is an efficient and flexible method for defining IP address ranges, allowing grouping of IP addresses to simplify routing and increase security! In short, it's an organized way to identify groups of IP addresses.

Key Pair Generation

First, you need to generate the public and private key pair (RSA, ECDSA or Ed25519) of your choice. This guide will focus on RSA keys. To generate the key pair, run the following commands in your terminal (we'll use Git Bash in this tutorial; on Linux these commands come standard with the system):

openssl genpkey -algorithm RSA -out private_key.pem -pkeyopt rsa_keygen_bits:2048
openssl rsa -in private_key.pem -pubout -out public_key.pem

You'll then be prompted for a password for the private key. You can just press Enter to have no password, or enter one - it's your choice.

After this, the key pair will be generated in the same directory, named private_key and private_key.pem.

The key that matters here for communication and validation with Avenia is the public_key.pem.

danger

Never share your private key with anyone!

Before we proceed directly to creating the API key, we should note that if we pass the public key as is as a request parameter, it would return an error because every space counts in the key. That is, if we encapsulated the following text in JSON it would fail:

warning

Do not use the following public key in your code — it is provided as an example. You must generate and use the key pair you created earlier.

-----BEGIN PUBLIC KEY-----
MIIBOgIBAAJBAKj34GkxFhD90vcNLYLInFEX6Ppy1tPf9Cnzj4p4WGeKLs1Pt8Qu
KUpRKfFLfRYC9AIKjbJTWit+CqvjWYzvQwECAwEAAQJAIJLixBy2qpFoS4DSmoEm
o3qGy0t6z09AIJtH+5OeRV1be+N4cDYJKffGzDa88vQENZiRm0GRq6a+HPGQMd2k
TQIhAKMSvzIBnni7ot/OSie2TmJLY4SwTQAevXysE2RbFDYdAiEBCUEaRQnMnbp7
9mxDXDf6AU0cN/RPBjb9qSHDcWZHGzUCIG2Es59z8ugGrDY+pxLQnwfotadxd+Uy
v/Ow5T0q5gIJAiEAyS4RaI9YG8EWx/2w0T67ZUVAw8eOMB6BIUg0Xcu+3okCIBOs
/5OiPgoTdSy7bcF9IGpSE8ZgGKzgYQVZeN97YE00
-----BEGIN END KEY-----

We need to replace the line breaks with \n, which the next command we'll use will do for us. To do this, just use Git Bash or if you're on Linux just run the following code:

sed '/^$/d' public_key.pem | sed ':a;N;$!ba;s/\n/\\n/g'

This will return (in a single line, without line breaks):

-----BEGIN PUBLIC KEY----------\nMIIBOgIBAAJBAKj34GkxFhD90vcNLYLInFEX6Ppy1tPf9Cnzj4p4WGeKLs1Pt8Qu\nKUpRKfFLfRYC9AIKjbJTWit+CqvjWYzvQwECAwEAAQJAIJLixBy2qpFoS4DSmoEm\no3qGy0t6z09AIJtH+5OeRV1be+N4cDYJKffGzDa88vQENZiRm0GRq6a+HPGQMd2k\nTQIhAKMSvzIBnni7ot/OSie2TmJLY4SwTQAevXysE2RbFDYdAiEBCUEaRQnMnbp7\n9mxDXDf6AU0cN/RPBjb9qSHDcWZHGzUCIG2Es59z8ugGrDY+pxLQnwfotadxd+Uy\nv/Ow5T0q5gIJAiEAyS4RaI9YG8EWx/2w0T67ZUVAw8eOMB6BIUg0Xcu+3okCIBOs\n/5OiPgoTdSy7bcF9IGpSE8ZgGKzgYQVZeN97YE00\n----------END PUBLIC KEY-----

API Key Registration

Now that we have the public key in a format that can be passed in a request, let's look at the parameters:

Field	Type	Description	Required
name	string	API Key identifier	Yes
publicKey	string	Public key in format (includes line breaks)	Yes
otp	string	OTP verification code	Yes
whitelistedIPs	array	List of allowed IP addresses (CIDR format). By default, all IPs will be released	No

info

If no whitelist IPs are provided, all IP addresses will be allowed by default. In other words, the whitelist will be set to:

{
  ...
  "whitelistedIPs": ["0.0.0.0/0"],
  ...
}

HTTP POST Request

https://api.sandbox.avenia.io:10952/v2/auth/api-keys/

Example JSON Body

{
  "name": "first api key",
  "publicKey": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEArtMQzJdnJKaFdPfj8n0H\nkHE/eI8yliI5KZhXls=....Il2iAJMmsjFclJHEioLGn8ei/eRhgLdRovbG6MledEjO7bNYOs9\nsQIDAQAB\n-----END PUBLIC KEY-----",
  "otp": "888888",
  "whitelistedIPs": ["0.0.0.0/0"]
}

cURL Example

curl -X POST "https://api.sandbox.avenia.io:10952/v2/auth/api-keys/" \
  -H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "first api key",
  "publicKey": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEArtMQzJdnJKaFdPfj8n0H\nkHE/eI8yliI5KZhXls=....Il2iAJMmsjFclJHEioLGn8ei/eRhgLdRovbG6MledEjO7bNYOs9\nsQIDAQAB\n-----END PUBLIC KEY-----",
  "otp": "888888",
  "whitelistedIPs": ["0.0.0.0/0"]
}'

JSON Response

As a response you'll get your API key (which is just its UUID). Save it somewhere, as you'll use it to authenticate to endpoints.

{
  "apiKey": "dc96d0f8-ac73-4abe-ade3-c6d14e3e22fb"
}

List All API Keys

Returns all data and API keys registered for an access.

HTTP GET Request

https://api.sandbox.avenia.io:10952/v2/auth/api-keys/

cURL Example

curl -X GET "https://api.sandbox.avenia.io:10952/v2/auth/api-keys/" \
  -H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

JSON Response

Here are all registered API Keys:

{
  "apiKeys": [
    {
      "id": "dc96d0f8-ac73-4abe-ade3-c6d14e3e22fb",
      "name": "first api keyaaa",
      "encryptionType": "RSA",
      "fingerPrint": "SHA256:9cxD0p...m/+GfhKbU",
      "whitelistedIPs": ["0.0.0.0/0"],
      "createdAt": "2025-03-27T18:29:44.450106Z",
      "updatedAt": "2025-03-27T18:29:44.450106Z"
    },
    {
      "id": "cfc2aaa8-6ca5-46bb-98be-70ceedb6f91f",
      "name": "second api key",
      "encryptionType": "RSA",
      "fingerPrint": "SHA256:9cxD0p...m/+GfhKbU",
      "whitelistedIPs": ["0.0.0.0/0"],
      "createdAt": "2025-03-19T03:23:07.369031Z",
      "updatedAt": "2025-03-19T08:32:40.42458Z"
    }
  ]
}

Update API Key

Here we can update the allowed IPs for an API Key following CIDR.

Field	Type	Description	Required
apiKey	string	The API Key you want to update	Yes
otp	string	OTP verification code	Yes
whitelistedIPs	array	List of allowed IP addresses (CIDR format). By default, all IPs will be released	Yes

warning

If no whitelist IPs are provided, it will return an error indicating that the whitelistIPs field is invalid.

HTTP PATCH Request

https://api.sandbox.avenia.io:10952/v2/auth/api-keys/

Example JSON Body

{
  "apiKey": "04e6e253-da90-468a-894e-fc898ae25feb",
  "otp": "558587",
  "whitelistedIPs": ["0.0.0.0/0"]
}

cURL Example

curl -X PATCH "https://api.sandbox.avenia.io:10952/v2/auth/api-keys/" \
  -H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{
  "apiKey": "04e6e253-da90-468a-894e-fc898ae25feb",
  "otp": "558587",
  "whitelistedIPs": [
    "0.0.0.0/0"
  ]
}'

As a response you'll receive confirmation that it was completely updated.

Delete API Key

Here we can delete an existing API Key.

URL Parameters

Field	Type	Description	Required
apiKey	string	The API Key you want to delete	Yes
otp	string	OTP verification code	Yes

HTTP DELETE Request

https://api.sandbox.avenia.io:10952/v2/auth/api-keys/?apiKey={apiKey}&otp={otp}

cURL Example

curl -X DELETE "https://api.sandbox.avenia.io:10952/v2/auth/api-keys/?apiKey=04e6e253-da90-468a-894e-fc898ae25feb&otp=558587" \
  -H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

As a response you'll get confirmation that this API Key was deleted.