Secrets

Secrets provide a secure way to store and manage sensitive credentials such as API keys, OAuth tokens, username/password combinations, and bearer tokens. These credentials can be used by AI agents, integrations, and skillsets to authenticate with external services without exposing sensitive data in your code or configuration files.

Secrets support multiple authentication types including plain text, basic auth, bearer tokens, and OAuth flows, making them versatile for various integration scenarios.

Creating Secrets

Creating a secret allows you to securely store credentials that can be referenced by name in your agents and integrations. When creating a secret, you need to specify the secret type, visibility, and the actual credential value.

Secrets can be either shared (stored on the platform) or personal (stored locally by each user). Shared secrets are accessible to all users within your organization, while personal secrets are user-specific.

To create a new secret:

Available Secret Types:

• plain - Simple text credentials
• basic - Username and password combinations
• bearer - API keys and bearer tokens
• oauth - OAuth tokens and refresh tokens
• template - Dynamic credential templates

Important Security Notes:

• Secret values are encrypted at rest and never exposed in API responses
• Only shared secrets store values on the platform; personal secrets require user authentication
• Once created, secret values can be updated but never retrieved directly
• Use appropriate visibility settings to control access to secrets

Listing Secrets

Retrieve a paginated list of all secrets in your workspace. This endpoint allows you to view all configured secrets, making it easy to manage and audit your stored credentials. The list includes metadata about each secret but never exposes the actual credential values for security reasons.

You can filter secrets by blueprint association and use pagination parameters to navigate through large sets of secrets. The response includes secret names, descriptions, types, visibility settings, and configuration details.

To list all secrets:

The response includes an array of secret objects with their metadata. You can use the cursor parameter for pagination to retrieve additional pages of results.

Query Parameters:

• cursor - Pagination cursor from previous response
• order - Sort order: asc or desc (default: desc)
• take - Number of items to retrieve per page
• blueprintId - Filter secrets by blueprint association
• meta - Filter by metadata fields

Note: The list endpoint never returns secret values. To verify if a secret is properly configured, use the verify endpoint instead.

Fetching Secret Details

Retrieve detailed information about a specific secret using its unique identifier. This endpoint returns the secret's metadata including its name, description, type, visibility settings, and configuration, but never exposes the actual credential value for security reasons.

Fetching secret details is useful when you need to display secret information in your user interface, update secret metadata, or verify secret configuration. The response includes all non-sensitive information about the secret, making it safe to use in client-side applications.

To fetch a specific secret:

Replace {secretId} with the unique identifier of the secret you want to retrieve. You can use either the secret's ID or its name in this parameter.

Response Fields:

• id - Unique secret identifier
• name - Secret name for reference
• description - Human-readable description
• kind - Secret kind: shared or personal
• type - Authentication type: plain, basic, bearer, oauth, or template
• visibility - Access control: private, protected, or public
• config - Additional configuration options
• blueprintId - Associated blueprint (if any)
• meta - Custom metadata
• createdAt - Creation timestamp
• updatedAt - Last update timestamp

Important: The secret value is never included in the response for security reasons. To verify that a secret is properly configured and authenticated, use the verify endpoint instead.

Updating Secrets

Update an existing secret's properties including its name, description, type, value, and visibility settings. This endpoint allows you to modify secret configuration without having to delete and recreate it, preserving any references to the secret in your agents and integrations.

When updating a secret, you can change most properties including the credential value itself. This is useful when rotating API keys, updating OAuth tokens, or modifying secret metadata. Only the secret owner can update a secret.

To update a secret:

Replace {secretId} with the unique identifier or name of the secret you want to update. You can update any combination of fields; only the fields you include in the request body will be modified.

Updatable Fields:

• name - Change the secret's reference name
• description - Update the description
• kind - Change between shared and personal
• type - Modify the authentication type
• value - Rotate or update the credential value (only for shared secrets)
• config - Update configuration options
• visibility - Change access control settings
• blueprintId - Associate with a different blueprint
• meta - Update custom metadata

Important Notes:

• Secret values can only be updated for shared secrets; personal secrets require user authentication through the OAuth flow
• Updating a secret's value does not affect existing references, but agents will use the new value in subsequent operations
• Consider testing updated credentials before deploying to production agents

Deleting Secrets

Permanently remove a secret from your workspace. This operation is irreversible and will delete the secret along with all stored credential data. Before deleting a secret, ensure that it is not being referenced by any active agents, integrations, or skillsets, as this could cause authentication failures.

Deleting a secret is useful when credentials are no longer needed, when rotating to a new authentication method, or when cleaning up old configurations. Only the secret owner can delete a secret.

To delete a secret:

Replace {secretId} with the unique identifier or name of the secret you want to delete. The request body should be an empty JSON object.

Important Warnings:

• This operation is permanent and cannot be undone
• Deleting a secret will cause authentication failures for any agents or integrations that reference it
• Consider updating references to use a different secret before deletion
• For OAuth secrets, the stored tokens are deleted but the OAuth authorization may still be active on the external service

Best Practices:

• Audit all usages of a secret before deletion using the platform's search features
• For sensitive credentials, consider revoking OAuth tokens before deleting the secret
• Document the reason for deletion in your change logs
• Test affected agents and integrations after secret deletion to ensure they handle the missing credentials gracefully

Authenticating OAuth Secrets

Initiate the OAuth authentication flow for a secret that requires user authorization. This endpoint is specifically designed for personal secrets or OAuth-based secrets that need to obtain access tokens through user consent. The endpoint returns an authentication URL that users must visit to grant permissions.

OAuth authentication is required for integrations with services like Google, Slack, GitHub, and other platforms that use OAuth 2.0 for authorization. This process ensures that secrets are bound to specific user accounts and include only the permissions that users explicitly grant.

To initiate OAuth authentication:

The response includes an authentication URL that the user must visit in their browser:

Authentication Flow:

1. Call this endpoint to get the authentication URL
2. Redirect the user to the returned URL in their browser
3. User grants permissions on the external service
4. External service redirects back to the platform with authorization code
5. Platform exchanges the code for access tokens and stores them securely
6. Secret is now authenticated and ready to use

Important Considerations:

• This endpoint only works with secrets configured for OAuth authentication
• The authentication URL is typically valid for a limited time (usually 10-15 minutes)
• Users must complete the OAuth flow in the same browser session
• After successful authentication, use the verify endpoint to confirm the secret is properly configured

Error Cases:

• Returns a conflict error if the secret type doesn't support OAuth authentication
• Returns not found if the secret doesn't exist
• Returns not authorized if the user doesn't have permission to authenticate the secret

Verifying Secret Status

Check whether a secret is properly configured and authenticated. This endpoint is essential for validating that credentials are available and ready to use, especially for OAuth-based secrets that require user authentication. The verify endpoint returns the secret's authentication status and provides an action URL if authentication is needed.

Verification is particularly important for personal secrets and OAuth secrets, where users must complete an authentication flow before the secret can be used. This endpoint helps you determine whether additional steps are required before agents can successfully use the secret.

To verify a secret's status:

The response indicates the authentication status and provides next steps if needed:

Status Values:

• authenticated - Secret is properly configured and ready to use
• unauthenticated - Secret requires user authentication (OAuth flow needed)

When Status is "unauthenticated": The response includes an action object with:

• type - The action type (typically "authenticate")
• url - The authentication URL the user must visit

Use Cases:

• Verify secrets before using them in agent configurations
• Check if OAuth tokens are still valid or need refresh
• Display authentication prompts in your user interface when secrets need setup
• Validate secret configuration during integration testing
• Audit secret readiness across your workspace

Best Practices:

• Always verify secrets before deploying agents to production
• Implement retry logic for authentication failures in your applications
• Use this endpoint to proactively detect expired or revoked OAuth tokens
• Cache verification results temporarily to avoid excessive API calls
• Display clear instructions to users when authentication is required

Revoking OAuth Secrets

Revoke the stored credentials for an OAuth secret, effectively disconnecting the integration with the external service. This endpoint is specifically designed for OAuth-based secrets and performs two key operations: it revokes the OAuth token with the external service and removes the stored credential from the platform.

Revoking a secret is different from deleting it. When you revoke an OAuth secret, the secret configuration remains intact, but the stored tokens are removed and invalidated with the external service. This allows you to re-authenticate the secret later without losing its configuration or references.

To revoke an OAuth secret:

Replace {secretId} with the unique identifier or name of the OAuth secret you want to revoke. The request body should be an empty JSON object.

What Happens During Revocation:

1. The platform attempts to revoke the OAuth token with the external service
2. The stored credential value is removed from the platform's secret store
3. The secret configuration (name, description, type) is preserved
4. Any agents or integrations using this secret will receive authentication errors
5. The secret can be re-authenticated using the authenticate endpoint

Use Cases:

• Immediately revoke access when credentials are compromised
• Disconnect integrations when no longer needed without losing configuration
• Rotate OAuth tokens by revoking and re-authenticating
• Comply with security policies requiring periodic credential rotation
• Remove access for users who no longer need it

Important Notes:

• This endpoint only works with shared OAuth secrets
• Revocation attempts to invalidate tokens with the external service, but success depends on the service's revocation API
• The secret must be re-authenticated before it can be used again
• Revocation is immediate and will cause authentication failures for active agents

Error Cases:

• Returns conflict if the secret is not a shared secret
• Returns not found if the secret doesn't exist or has already been revoked
• Returns not authorized if the user doesn't have permission to revoke the secret