Authentication
Every call to Plumma® Connect must carry two HTTP headers. Both are required, and a call that is missing either one is refused.
| Header | Value |
|---|---|
x-plumma-connect-api-key |
Your API key, exactly as you copied it from the console. |
x-plumma-connect-app-id |
The application the call belongs to, as shown in the console, in the
format NN-XXXXXXX-APP (for example 11-3fa9c2e-APP). |
POST /services/api HTTP/1.1
Host: connect.plumma.it
Content-Type: application/json
x-plumma-connect-api-key: YOUR_API_KEY
x-plumma-connect-app-id: YOUR_APP_IDWhat the key is
Your API key is a digital certificate that Plumma issues and signs for your account. It states who the key belongs to and that it was issued for Plumma® Connect, and Plumma checks both on every call.
The key identifies you, the customer. It holds nothing about the people whose phone numbers you check. Keep it secret all the same: anyone who has it can make calls in your name.
Key validity and expiry
A key is valid for 365 days from the day it is issued, and it expires
after that. An expired key does not renew itself: every call made with it
is refused with 401 Unauthorized until you put a new key
into your integration.
Every 30 days Plumma emails you a report on the state of your keys, with the expiry date of each one, so you can replace a key before it expires. You can also see a key's expiry date in the console at any time.
To renew a key, regenerate it before it expires (see Regenerating a key). The new key is valid for another 365 days.
One key for demo and real numbers
You get one key per organization, and there is no separate test key. The same key and the same endpoint work for demo numbers and for real ones. Demo numbers are never charged. A real number is charged for each command that is served.
Enabling a key for an application
Plumma enables each key for each application separately. A key works with an application only once Plumma has enabled it for that application. A new key, or an application you have just added, cannot be used until this has happened.
Copying your key
You can copy a key from the console once only. After that the console will not show it again, so save it somewhere secure, such as a secrets manager, as soon as you copy it. If you lose it, regenerate it.
Regenerating a key
You can regenerate your key at any time from the API keys menu in the console. The new key is enabled for the same applications as the old one, so you do not need to ask Plumma again. The old key stops working as soon as the new one is issued.
Calls made with the old key are refused from then on, so be ready to put the new key into your integration straight away.
To shut a key off without getting a new one, for example if it may have been exposed, contact Plumma.
When a call is refused
There are two kinds of refusal, and each calls for a different action:
-
401 Unauthorized: the key itself cannot be used, because it cannot be read, has expired, or is not valid yet. Regenerate it. -
403 Forbidden: the key is fine, but the call is still not allowed. A header is missing, the application id is not in theNN-XXXXXXX-APPformat, the key was issued for a different purpose, or the key is not enabled for that application. A new key will not help: the key has to be enabled for the application.
Both answer with application/problem+json, and the
detail field explains in plain words which case it is.