As teams grow and APIs become more integral to your workflow, more and more people will use Postman’s collection access keys feature to grant other users access to a single collection. This is a fast and easy way to share with other users, especially users outside of your team.
However, these keys can pose a risk if left active for too long, as they might be forgotten about. This can lead to unnecessary access remaining open. For extended collaboration, it’s better to use built-in team and partner access controls.
The Postman API provides an interface to programmatically manage collection access keys, ensuring that your collections are accessible to the right people and secure according to your organization’s policies.
In this post, we’ll cover the latest updates to the Postman API’s collection access key management features and walkthrough a use case to help you understand how you can leverage them.
What does the Postman API do?
Postman API’s collection access keys endpoints are useful for managing access in large teams or automating security measures, even if the person who issued the key has left the team.
Key Features
- GET /collection-access-keys — Gets a list of access keys associated with the authenticated user’s entire team.
- DELETE /collections-access-keys/{keyId} — Revokes an access key when it’s no longer needed to prevent further access.
Benefits of the Postman API for collection access management
- Granular Control. Programmatically create, track, and revoke access to API collections, ensuring only the right people have access.
- Enhanced Security. Automatically expire unused access keys after 60 days and monitor key usage for compliance.
- Auditability. Track the history of each access key, including creation time, its last use, and its expiration.
Understanding collection access keys
Collection access keys grant a user or team access to a specific Postman Collection. By default, they’re valid for 60 days. When someone uses the access key, its expiration increases by another 60 days. If it’s unused, it’ll expire after the initial 60 days.
An access key consists of the following properties:
- ID — The access key’s unique ID.
- Status — Indicates whether the access key is active.
- Created — When the access key was created.
- Expires After — When the access key will expire.
- Last Used — The last time the access key was used. If unused, this is an empty value.
Retrieve collection access keys
To view all of your collection’s existing access keys, you can use the GET /collection-access-keys endpoint. Here’s an example request:
GET /collection-access-keys
X-Api-Key: YOUR_API_KEY
The response will look similar to the following:
{
"data": [
{
"id": "Njg5O…",
"token": "PMAT-**********************43BR",
"status": "ACTIVE",
"teamId": 123,
"userId": 12345678,
"collectionId": "12345678-12ece9e1-2abf-4edc-8e34-de66e74114d2",
"expiresAfter": "2024-06-11T13:21:11.000Z",
"lastUsedAt": "",
"createdAt": "2024-04-12T13:21:11.000Z",
"updatedAt": "2024-04-12T13:21:11.000Z",
"deletedAt": null
}
],
"meta": {
"nextCursor": "b2Zmc2V0PTEwJmxpbWl0PTEw",
"prevCursor": ""
}
}
This response shows all the active access keys for the authenticated user, including details like when it was created and when it was last used.
Revoking a collection access key
You can revoke a collection access key with the DELETE /collection-access-keys/{keyId} endpoint. Here’s an example revocation request:
DELETE /collection-access-keys/Njg5O…
X-API-Key: YOUR_API_KEY
On success, the endpoint returns an HTTP 204 No Content response, indicating that the key was revoked:
HTTP/1.1 204 No Content
Use Case: Implementing an access policy
In this use case scenario, an organization has a security policy to maintain active and recent access keys for Postman Collections. Their security policy defines two critical rules:
- Access keys should not be older than 10 days. This ensures that no key stays active for too long, reducing the risk of misusing forgotten or stale keys.
- Access keys should be disabled if they are not used for more than 3 days. This helps prevent unused keys from lingering and potentially becoming a security vulnerability.
The following are JavaScript examples for both use cases: finding and revoking access keys older than 10 days and keys that have been inactive for more than 3 days.
Revoke access keys older than 10 days
// Function to get collection access keys
async function getAccessTokens() {
const response = await fetch('/collection-access-keys', {
method: 'GET',
headers: {
'Content-Type': 'application/json',
'X-API-Key': 'your-api-key'
}
});
return response.json();
}
// Function to revoke a token by ID
async function revokeToken(tokenId) {
await fetch(`/collection-access-keys/${tokenId}`, {
method: 'DELETE',
headers: {
'Content-Type': 'application/json',
'X-API-Key': 'your-api-key'
}
});
}
// Calculate the date 10 days ago
const tenDaysAgo = new Date();
tenDaysAgo.setDate(tenDaysAgo.getDate() - 10);
// Fetch and process access tokens
getAccessTokens().then(tokens => {
tokens.data.forEach(token => {
const createdAt = new Date(token.createdAt);
// If token was created more than 10 days ago, revoke it
if (createdAt < tenDaysAgo) {
console.log(`Revoking token: ${token.id}, created on: ${token.createdAt}`);
revokeToken(token.id);
}
});
});
Revoke access keys inactive for more than 3 days
// Calculate the date 3 days ago
const threeDaysAgo = new Date();
threeDaysAgo.setDate(threeDaysAgo.getDate() - 3);
// Fetch and process access tokens
getAccessTokens().then(tokens => {
tokens.data.forEach(token => {
const lastUsedAt = token.lastUsedAt ? new Date(token.lastUsedAt) : null;
// If token hasn't been used for more than 3 days, revoke it
if (lastUsedAt && lastUsedAt < threeDaysAgo) {
console.log(`Revoking inactive token: ${token.id}, last used on: ${token.lastUsedAt}`);
revokeToken(token.id);
}
});
});
Conclusion
The Postman API’s collection access key management feature is a powerful tool for developers, IT professionals, and security teams who need to automate access control and ensure tight security. With features to retrieve, manage, and revoke keys, the Postman API enables you to streamline security practices while ensuring smooth collaboration across your team.
Do you have a specific use case with Postman’s collection access keys? How would you use the Postman API in your security practices? Feel free to comment and tell us about your own use cases!