The API Keys page lists your organization's API keys and lets you create, edit and delete them. An API key lets a script or tool call the Pipe17 API on your behalf, with the permissions you choose for it and, optionally, only from IP addresses you allow. Use API keys for one-off scripts, testing and tools such as the Pipe17 MCP Server. To connect another system to Pipe17 on an ongoing basis, build a Custom Integration instead.
Before you start
- Where to find it: go to Settings > API Keys.
- Permissions: what you can do depends on your role's apikey permissions (listed as API Key in the roles table):
| To | You need |
|---|---|
| See API Keys in the menu and the list | apikey List |
| Open a key and see its value | apikey Read |
| Create a key | apikey Create (otherwise Create API key is greyed out) |
| Save changes to a key | apikey Update |
| Delete keys | apikey Delete (otherwise Delete is greyed out) |
The built-in Administrator and Developer roles have all five. The User role has List only, so users with that role can see the list but can't open or create keys. To change a role, see Managing Roles and Permissions.
API key or Custom Integration?
When you create a key, Pipe17 shows a warning: API keys are not for system-to-system integrations. A user API key belongs to the person who created it and carries only the permissions they could give it. It may also get masked values for sensitive customer data (such as PII), depending on that person's access. Integrations built on a user API key can therefore stop working or return masked data without notice. If you're connecting another system to Pipe17, use a Custom Integration, which has its own integration keys.
Integration keys and the Child-Org Management Key used by OEM partners aren't managed on this page. For the Child-Org Management Key, see OEM Automated Secondary Org Management.
The API Keys list
| Column | Shows |
|---|---|
| Name | The key's name. Click it to open the key. |
| Description | What the key is for. |
| Allowed IPs | The IP addresses the key can be used from. 0.0.0.0 means any IP address (no restriction). |
| Creator | The user who created the key (click to see them in Users). SYSTEM means Pipe17 created it, for example the Automation Engine key. Deleted user means the creator's user was deleted. Parent org user means a user of your parent organization created it. |
| Created, Updated | When the key was created and last changed. |
You can show, hide and reorder columns with the columns button at the top right. The list has no search.
Keys that Pipe17 creates for integrations and connectors don't appear here. Find those on the integration's page.
The Automation Engine key
Most organizations have a key named Automation Engine with creator SYSTEM. Pipe17 uses it to run your automations. You can't view or copy its value. Don't rename it, change its permissions or IP restrictions, or delete it (including in a bulk delete), or your automations can stop working. If you think it needs attention, submit a support request.
Create an API key
To create an API key:
- Go to Settings > API Keys and click Create API key.
- Enter a Name and a Description. Both are required; an empty field shows Required. Use the description to say what the key is for and who uses it.
- Under Permissions, choose what the key can do (see Choose permissions below).
- Under IP Restrictions, choose None or Only allowed IPs (see Restrict a key to IP addresses below).
- Click Save. If your organization asks for a reason for changes, enter it and confirm.
Pipe17 shows Created API Key and opens the key's page, where you can copy the key value. New keys start with no permissions selected, so a key you save without choosing any can't call the API.
Choose permissions
The Permissions table has one row per entity (for example orders, products, inventory) and a checkbox for each action: Create, Read, Update, List and Delete. The checkboxes in the top row select or clear that action for every entity where you can grant it. Hover over the ? next to an entity to see what it covers.
To start from a preset, open Select a template and choose one. Choosing a template replaces your current selection.
| Template | Gives the key |
|---|---|
| Read Only API | Read and List on almost every entity |
| Update API | Read, Update and List on almost every entity. The exceptions entity gets Read and List only. |
| Create API | Create, Read and List on almost every entity. The exceptions entity gets Read and List only. |
| Account Management | Full access to API keys, connectors and organizations, and read access to the account |
| Developer | Full access to API keys, connectors, integrations, mappings, routings, webhooks, inventory rules and locations |
| User Management | Full access to users and roles |
| No Access | Clears every permission |
After you pick a template, you can still change any enabled checkbox.
The roles page in Settings > Roles has templates with the same names, but they fill in different permissions there. The table above describes the templates on the API key page.
Why some checkboxes are greyed out:
- You can't give a key more access than you have. Any action your own role doesn't allow is greyed out, and templates skip it.
- Some actions can never be given to an API key, for example deleting exceptions or tracking records. Hovering over these shows Editing this permission is not allowed.
Restrict a key to IP addresses
By default, IP Restrictions is set to None: the key works from any IP address, and the list shows 0.0.0.0.
To limit a key to specific addresses:
- Under IP Restrictions, select Only allowed IPs.
- In Allowed IPs, type an IPv4 address (for example
203.0.113.10) or a CIDR range (for example203.0.113.0/24, from/0to/32). - Press Enter. Repeat for each address the key will be used from.
- Click Save, and enter a reason if your organization asks for one.
To remove the restriction, select None and save.
IPv6 addresses and hostnames aren't accepted. Enter the public address that Pipe17 sees for the machine or service making the calls; an address on your local network is usually different. Don't add 0.0.0.0 to a restricted list, because it allows every address.
A call from any other address is rejected with a 403 Forbidden error.
View and copy a key
To get a key's value:
- Go to Settings > API Keys and click the key's name.
- In the API Key field, click the copy icon to copy the value, or the eye icon to show it.
The value is hidden until you show it, and the page reminds you: Do not let anyone see this key. It isn't a one-time display: anyone with apikey Read permission can open the key and copy it later. Treat it like a password. Store it in a secrets manager or an environment variable, not in code, email or chat.
If a key's value is exposed, create a new key, switch your script to the new value, and then delete the old key.
The page also shows the key's Creator and, at the bottom, an Activity section with the key's change history.
Use a key in API calls
Send the key in the X-Pipe17-Key header with each request to the Pipe17 API at https://api-v3.pipe17.com/api/v3. For example:
curl -H "X-Pipe17-Key: <your API key>" https://api-v3.pipe17.com/api/v3/ordersThe key already belongs to your organization, so you don't need to send your organization key. For endpoints and examples, see Pipe17 API References.
The Pipe17 MCP Server takes the same API key in a different way: the organization key goes in the server URL (https://mcp.pipe17.com/mcp/<your org key>) and the API key is sent as Authorization: Bearer <your API key>. For setup steps, see Pipe17 MCP Server.
Edit a key
To change a key:
- Go to Settings > API Keys and click the key's name.
- Change the Name, Description, Permissions or IP Restrictions.
- Click Save, and enter a reason if your organization asks for one.
Pipe17 shows Updated API Key. The key value doesn't change when you edit a key, so scripts that use it keep working with the new permissions and IP rules. Pipe17 caches a key's access, so changes can take up to 15 minutes to apply to API calls.
Delete keys
Deleting a key is permanent and can't be undone. Any script, tool or integration that uses the key stops working, usually within 15 minutes (the time Pipe17 caches a key's access). The confirmation warns: Deleting API Keys may disconnect your integrations and cause interruption to your workflows. Update anything that uses the key first.
To delete one key:
- Open the key and click Delete at the top right.
- In the Delete API Key dialog, click Delete.
To delete several keys:
- On the API Keys list, select the checkbox next to each key.
- Click Delete above the list.
- In the Delete API Keys dialog, click Delete.
If your organization asks for a reason for changes, enter it to finish. Pipe17 shows Deleted API Key (or Deleted API keys for several).
When people leave or change roles
A key keeps the permissions it was saved with:
- Changing the creator's role doesn't change the key's permissions. Edit the key if it should have less access.
- Deleting or disabling the creator's user doesn't delete their keys. A deleted creator shows as Deleted user in the list.
- If the creator's access to your organization expires, their keys stop working.
The create page warns that user keys can stop working when their creator is removed or their access changes. Don't rely on that to cut off access, and don't rely on the key to keep working either: when a person leaves, replace any script that uses their key with a new key and delete the old one.
Review the list from time to time and delete keys nobody uses. Pipe17 doesn't show when a key was last used.
Troubleshooting
- "You are not authorized to grant these permissions" when you save
The key includes a permission your own role doesn't have. Clear it, or ask an admin to add it to your role. - API calls return 401 Unauthorized
Pipe17 didn't recognize the key: the value is wrong, you sent the key's name instead of its value, or the key was deleted. Copy the value again from the key's page, and check that the header isX-Pipe17-Key. - API calls return 403 Forbidden
The key doesn't have the permission the call needs (for example Create on orders), or the call comes from an IP address that isn't in Allowed IPs. Check both on the key's page. It can also mean the creator's access to the organization has expired. - API calls return 401 even though the key is correct
Check the header name. Pipe17 reads the key only fromX-Pipe17-Key; a key sent inx-api-keyorAuthorizationisn't recognized by the REST API. - Calls work from one network but fail with 403 from another
The key is set to Only allowed IPs and the caller's public address isn't in the list. Add that IPv4 address or range, press Enter and save. - A field shows an error when you add an IP address
Enter one IPv4 address or CIDR range at a time, such as203.0.113.10or203.0.113.0/24, and press Enter. IPv6 addresses and hostnames aren't accepted. - Name or Description shows Required
Both fields are required. Fill them in and save again. - A permission or IP change doesn't seem to apply yet
Pipe17 caches a key's access for up to 15 minutes. Wait and try again, and check that your script uses the key you edited. -
Create API key or Delete is greyed out
Your role doesn't have apikey Create or Delete permission. Ask an admin to update your role. - I can see the list but can't open a key
Your role has apikey List but not Read. Ask an admin to add Read. - Customer data comes back masked
User API keys get masked values for sensitive fields unless the creator is allowed to unmask them. For a system integration, use a Custom Integration instead. - You can't see the Automation Engine key's value
That's expected: its value is protected. Leave the key unchanged and submit a support request if automations are failing.
Need Help?
If you need additional assistance:
- Use Ask Pippen, our AI agent, located at the top of the platform page.
- Submit a support request with as much relevant detail as possible. Learn how to submit a request.
We're here to help you succeed with your operations.
Comments
0 comments