Overview

API keys provide secure, programmatic access to the yWorkflow REST API. Each API key is scoped to a specific organization and can be configured with different roles and permissions.

Default Tab: The API Keys tab is the default tab when you first log into the application. You can access it from the main dashboard.

Creating API Keys

1

Navigate to API Keys Tab

Open the main dashboard and select the "API Keys" tab (it's selected by default).

2

Fill in Key Details

The form is pre-filled with "new" key selected. Enter the following:

  • Label: A human-readable identifier (required)
  • Role: Optional role identifier (e.g., "admin", "user", "viewer")
  • Admin: Check this box if the key should have admin privileges
3

Create the Key

Click "Create API Key" to generate the new key.

4

Save the Key

Important: Store your API key securely. You can view the key value at any time from the API keys page, and you can rotate the key to generate a new value whenever needed.

💡 Tip: From the API keys creation page, there's a link to the Swagger UI. If you click it, your API key will be automatically configured in Swagger, so you can test the API directly from the interactive documentation without manually entering your key.

Using API Keys

Once you have an API key, include it in all REST API requests using the X-API-KEY header: 

curl -X 'GET' \
  'https://app.yworkflow.com/api/definitions' \
  -H 'accept: application/json' \
  -H 'X-API-KEY: wkf_123456789012'

Note: API keys are organization-scoped. Each key only works for the organization it was created in. When you switch organizations in the app, you'll see different API keys.

Managing API Keys

Editing API Keys

You can edit the following properties of existing API keys:

  • Label: Update the human-readable identifier
  • Role: Change the role identifier
  • Admin: Toggle admin privileges

The save button is only enabled when changes are detected. Validation ensures the label is always provided.

Viewing API Key Values

API key values are hidden by default for security. You can:

  • Click the "Show" button to reveal the key value
  • Click "Copy" to copy the key to your clipboard
  • Keys stored in sessionStorage can be viewed during the current session

Rotating API Keys

Key rotation generates a new API key and invalidates the old one. This is useful for security best practices:

  • Generate a new key with the same properties
  • The old key is immediately invalidated
  • The new key value is displayed once (same as creation)
  • You have a brief window to update your applications before the old key stops working

Deleting API Keys

You can delete API keys that are no longer needed. Deleted keys are immediately invalidated and cannot be recovered.

API Key Properties

Label
Human-readable identifier for the key (required)
Role
Optional role identifier for application-level role management
Admin
Boolean flag indicating admin privileges (may affect API permissions)
Active
Status indicating whether the key is active or inactive
Created At
Timestamp when the key was created
Hash
Unique identifier for the key (not the actual key value)

Security Best Practices

🔐 Store Keys Securely

Never commit API keys to version control. Use environment variables or secure secret management systems.

🔄 Rotate Regularly

Rotate your API keys periodically, especially if you suspect they may have been compromised.

👥 Use Role-Based Keys

Create separate API keys for different roles or services. This limits the impact if a key is compromised.

🗑️ Delete Unused Keys

Remove API keys that are no longer in use to reduce your attack surface.

Previous: Authentication Next: Workflow Definitions