API keys
API Keys lists the keys that partner software uses to reach the comrce cloudprint API. A partner such as a shipping tool gets one key. Customers then allow that partner to use their account. Here you create a key, set its areas, switch it off or delete it. Open it with AdministrationAPI Keys.
What you can do here
Section titled “What you can do here”- Create a key for a partner. comrce cloudprint generates the key and shows it once in a dialog. Create a key
- Decide what the partner may do. Five areas, from general functions to the archive. Edit a key
- Switch a key off or on. One click in the list. Switch a key off
- Delete a key. Systemadministrator only, after a confirmation. Delete a key
The screen at a glance
Section titled “The screen at a glance”
What this screenshot shows
- Screen
- API Keys
- Highlighted
- switches the key on
- Also visible
- Three partner keys without account, one private key of Musterhandel GmbH; Actions per row: activate or deactivate, edit, delete
- Purpose
- manage partner API keys
| Region | What it shows | What you do there |
|---|---|---|
| Plus button next to the heading | Tooltip API Key erstellen (create API key) | Create a key |
| Suche (search) | Your search term | Filter the list as you type |
| Table | ID, Kurzname (short name), Anzeigename (display name), Accountname, Kontakt E-Mail (contact email), Aktiviert (active) | Find the key |
| Actions per row | API Key aktivieren or API Key deaktivieren, API Key bearbeiten (edit), API Key löschen (delete) | Act on the key |
Two kinds of keys share the list:
- Partner keys have no Accountname. Every customer can allow the partner. You create them here.
- Private keys belong to one account and show its name and ID, such as Musterhandel GmbH 1842. Customers create them themselves for their own software.
Create a key
Section titled “Create a key”- Select the plus button next to API Keys. An empty API Key page opens. Aktiviert is ticked, and so are the areas Allgemein and Eingabe.
- Fill in Anzeigename, Kurzname and the partner’s email address in Kontaktname.
- Enter the Return URI, the address of the partner’s software that customers return to after allowing it.
- Tick the areas the partner needs, and Einfacher Zugriff erlaubt if it uses the simple access.
- Select Ok. The dialog Der neue API Key (the new API key) shows the generated key.
What this screenshot shows
- Screen
- API Key
- Highlighted
- “e8b3d6f2-0a7c-4e1d-b9f4-6c2a8d0e5b13”: shows the generated key to pass on to the partner
- Also visible
- Dialog Der neue API Key with the key value
- Purpose
- create a key for a partner
Pass the key to the partner’s contact. It stays readable later in the field Key of the key’s page. A new key here is always a partner key: the page has no field for an account.
Edit a key
Section titled “Edit a key”Select API Key bearbeiten in the key’s row. Change the fields and select Ok. The list opens again. Abbrechen returns without saving.
What this screenshot shows
- Screen
- API Key
- Highlighted
- “Einfacher Zugriff erlaubt”: offers the key for the simple API access
- Also visible
- Read-only Key, Accountname and Loginfehler; Areas Allgemein, Eingabe, Ausgabe ticked
- Purpose
- edit one partner key
The areas under Zugriff auf folgende Bereiche: (access to these areas) decide what the partner may do:
| Area | What the partner may do |
|---|---|
Allgemein (general) | Statistics and metrics, and register webhooks where other areas allow it |
Eingabe (input) | Send documents into comrce cloudprint, read the input endpoints and check job status |
Ausgabe (output) | Register as a Service Client and create webhooks |
Verwaltung (management) | Manage the whole account. The description on screen is cut off mid-sentence. |
Archiv (archive) | Access the internal archive |
Example: a shipping tool that sends labels to print needs Allgemein and Eingabe. Software that prints itself, as a Service Client does, also needs Ausgabe.
Switch a key off
Section titled “Switch a key off”Select API Key deaktivieren in the key’s row. It takes effect at once, without a confirmation. The tick under Aktiviert disappears, and the row offers API Key aktivieren instead.
Delete a key
Section titled “Delete a key”- Select API Key löschen in the key’s row. A confirmation names the key’s ID and display name.
- Select Ok. The key disappears from the list.
Every control, explained
Section titled “Every control, explained”
Every control, explained
Section titled “Every control, explained”Einfacher Zugriff erlaubt
Section titled “Einfacher Zugriff erlaubt”The checkbox below Aktiviert on the key’s page.
Offers the partner in the simple API access, where customers create a user name and password for it. Without it the partner appears only for the OAuth access.
Simple partner software can’t run an OAuth sign-in. It signs in with fixed credentials instead.
Loginfehler
Section titled “Loginfehler”The read-only field Loginfehler (login errors) on the key’s page.
Counts failed sign-ins with this key. Above 50, comrce cloudprint refuses sign-ins with This api key is currently locked due to too many login attempts. The app never sets the count back to zero. A locked key then works only about once a day.
A high count means the partner sends wrong credentials. Ask the developers to reset the counter once the partner fixed them.
Kontaktname
Section titled “Kontaktname”The field Kontaktname (contact name) on the key’s page.
Holds the partner’s contact email address. The list shows it as Kontakt E-Mail.
Despite the label, enter an email address: it is what the list shows.
Return URI
Section titled “Return URI”The field Return URI on the key’s page.
The address of the partner’s software. After a customer allows the partner, comrce cloudprint sends them back there.
A wrong address leaves customers stranded after they allowed the partner.
Other controls on this page (7)
| Control | What it does | Why |
|---|---|---|
| Key | The key value, read-only | Pass it on again |
| Accountname | The account of a private key, read-only | Tell private keys from partner keys |
| Anzeigename | The name customers see for the partner | Recognisable partner |
| Kurzname | A short identifier of the partner | Internal reference |
| Beschreibung (description) | Free text about the partner | Context for colleagues |
| Aktiviert | Same as the switch in the list | – |
| Suche | Filters as you type, also by key value and return URI | Find a key from a partner’s question |
Who sees what
Section titled “Who sees what”
Who sees what
Section titled “Who sees what”| Part of the page | Systemadministrator | Supporter |
|---|---|---|
| List, search, create, edit, switch on and off | yes | yes |
| API Key löschen | yes | no |
What you need to know
Section titled “What you need to know”
What you need to know
Section titled “What you need to know”| Topic | Fact |
|---|---|
| Key value | Generated by comrce cloudprint, can’t be changed |
| Switching off | Stops new authorizations only |
| After deleting | Gone for good; only a Systemadministrator deletes |
| Login error lock | Above 50 failed sign-ins, no reset in the app |
| New keys here | Always partner keys without account |
Frequently asked questions
Section titled “Frequently asked questions”
Frequently asked questions
Section titled “Frequently asked questions”Creating
Section titled “Creating”Where do I see the key again after closing the dialog?
Section titled “Where do I see the key again after closing the dialog?”Open the key with API Key bearbeiten. The field Key at the top shows the value, read-only. Anyone with access to API Keys can read it.
Which areas should a new partner get?
Section titled “Which areas should a new partner get?”Only what the software needs. A tool that sends documents to print needs Allgemein and Eingabe, which is also the default for a new key. Add Ausgabe only for software that prints itself like a Service Client.
Can I create a key for one customer only?
Section titled “Can I create a key for one customer only?”Not here. A key created on API Keys has no account and is offered to every customer. Customers create private keys for their own account themselves.
Can I change a key’s value?
Section titled “Can I change a key’s value?”No. comrce cloudprint generates the value when you create the key. To give a partner a new value, create a new key and delete the old one.
Switching off and deleting
Section titled “Switching off and deleting”Does switching a key off stop the partner?
Section titled “Does switching a key off stop the partner?”Only for new customers. Customers who allowed the partner before keep their access, and so does the simple access. Delete the key to stop every request.
Why can’t I delete a key?
Section titled “Why can’t I delete a key?”API Key löschen is for the comrce cloudprint role Systemadministrator only. As a Supporter you don’t see it. Switch the key off and ask a Systemadministrator.
What happens to customers when I delete a key?
Section titled “What happens to customers when I delete a key?”Their partner software can’t reach comrce cloudprint any more. Every request with the deleted key is refused as Api key is not valid. The customers need a new partner key.
Errors
Section titled “Errors”A partner reports “This api key is currently locked”. What now?
Section titled “A partner reports “This api key is currently locked”. What now?”The key has more than 50 failed sign-ins in Loginfehler. Ask the partner to fix their credentials. Then ask the developers to reset the counter, because the app can’t.
A customer can’t allow a partner. Why?
Section titled “A customer can’t allow a partner. Why?”Check Aktiviert in the list. A switched-off key refuses new customers with Der gewünschte API Partner existiert nicht oder ist nicht für neue Anmeldungen freigeschaltet. Also check that the partner asks only for areas ticked on its key.
Troubleshooting
Section titled “Troubleshooting”
Troubleshooting
Section titled “Troubleshooting”| Symptom | What to check |
|---|---|
| Der gewünschte API Partner existiert nicht oder ist nicht für neue Anmeldungen freigeschaltet. | The key is switched off. Switch it on in the list. |
| Der gewünschte API Partner darf auf ein oder mehrere der angegebenen Scopes nicht zugreifen. | The partner asks for an area that isn’t ticked on its key. Tick it, or ask the partner to drop it. |
| This api key is currently locked due to too many login attempts. | Loginfehler is above 50. The developers reset it. |
| Api key is not valid | The key was deleted, or the partner sends a wrong value. Compare with Key. |
| API Key löschen is missing | Your role is Supporter. |
Related
Section titled “Related”- comrce cloudprint administration
- Accounts: the account a private key belongs to
- Change identity: see a customer’s API access settings as they do