API Keys: Create, Delete and Manage

An API key is the credential your application sends to the ReportingCloud Web API in place of the user name (the email address you signed up with) and password of your account. You create keys on the Manage Account page of the ReportingCloud portal or with the Web API, give each application a key of its own and delete a key when it is no longer needed or has leaked. Read on for how to create, use, delete and manage keys, and how to keep them safe.

Why Use API Keys

Each request authenticates either with an API key or with the user name and password of the account in a Basic header. Text Control recommends API keys:

They are random. A key is a randomly generated string of more than 40 characters, while a password is chosen by a person and is often used on other sites as well.
They are independent of your password. When you change the password of the account, code that sends a key keeps working.
They are replaceable. An account holds up to 10 keys. You delete a key and create a new one without touching the account or the other keys.
They are traceable. The Transaction Monitor of the portal shows which key each request used, so one key per project or application tells you where the documents came from. See Transactions and Statistics.

Create a Key in the Portal

Log in to the portal at https://portal.reporting.cloud/.
Click Manage Account in the Account section of the side menu.
Under API Keys, click Create Key.
The new key appears in the list above the button. Copy it into the configuration of your application, for example into an environment variable:
```
export REPORTINGCLOUD_API_KEY="<API key>"
```

The samples of this documentation read the key from the environment variable REPORTINGCLOUD_API_KEY. Manage Account describes the other settings of the page.

Send the Key With a Request

A request carries the key in its Authorization header, after the word ReportingCloud-APIKey and a space:

Authorization: ReportingCloud-APIKey <API key>

The same header works for every endpoint of the Web API. Authentication shows complete requests with curl and the SDKs, and the Basic header as the alternative.

Delete a Key

On Manage Account, click Delete Key next to the key in the API Keys list. Requests that send a deleted key are refused at once, with status 403 and the text:

Invalid username/password combination or invalid APIKey

Before you delete a key that an application still uses, create a new one, change the configuration of the application and then delete the old key. Authentication in the troubleshooting section lists the other reasons why a request with a key is refused.

Manage Keys With the Web API

Three endpoints of the account group manage keys from a script or an application:

Endpoint	What it does
GET /v1/account/apikeys	Lists the keys of the account
PUT /v1/account/apikey	Creates a key and returns it
DELETE /v1/account/apikey	Deletes the key given in the `key` query parameter

The endpoints accept an API key or the Basic credentials of the account, so you can create the first key with your user name and password and use keys from then on.

List the Keys

curl "https://api.reporting.cloud/v1/account/apikeys" \
  -H "Authorization: ReportingCloud-APIKey $REPORTINGCLOUD_API_KEY"

The response is an array with one object per key. active says whether a key is active, but it isn't used yet: every key reads true, and a deleted key is removed from the list:

[
  { "key": "<first API key>", "active": true },
  { "key": "<second API key>", "active": true }
]

Create a Key

curl --request PUT "https://api.reporting.cloud/v1/account/apikey" \
  -H "Authorization: ReportingCloud-APIKey $REPORTINGCLOUD_API_KEY" \
  -H "Content-Length: 0"

The request has no body, but the Web API requires a Content-Length header or a chunked body on a PUT request: without either, it answers with status 411 (Length Required). The response body is the new key as a JSON string:

"<new API key>"

Delete a Key

curl --request DELETE "https://api.reporting.cloud/v1/account/apikey?key=<API key to delete>" \
  -H "Authorization: ReportingCloud-APIKey $REPORTINGCLOUD_API_KEY"

On success, the Web API answers with status 200 and an empty body. A key that the account doesn't have gets status 404.

In the SDKs

Each SDK has a method per endpoint:

SDK	List	Create	Delete
.NET	`GetAccountAPIKeys()`	`CreateAccountAPIKey()`	`DeleteAccountAPIKey(key)`
PHP	`getApiKeys()`	`createApiKey()`	`deleteApiKey($key)`
Java	`getAPIKeys()`	`createAPIKey()`	`deleteAPIKey(key)`
Ruby	`get_api_keys`	`create_api_key`	`delete_api_key(key)`

The Java and Ruby SDKs manage keys like the others but authenticate their own requests with the user name and password only. Installing an SDK adds an SDK to your project.

Keep Your Keys Secret

Whoever holds one of your keys can use your account, its templates and its quota. Treat a key like a password:

Keep it out of source code and repositories. Read it from an environment variable or the configuration of your server.
Keep it on the server. A key in a script that runs in the browser is visible to every visitor of the page.
Use one key per application, so that a leaked key can be replaced without changing the others.
Delete a key that has leaked and create a new one. Your password stays as it is.

Data Security and Privacy describes how connections are encrypted and what ReportingCloud stores.

Next Steps

Authentication: the API key and Basic headers in requests and in the SDKs.
Installing an SDK: add the .NET, PHP, Java or Ruby SDK to your project.
Web API: create a first document with the key.