Skip to main content

​
Overview

Updates the credentials for a specific server in your stack. This endpoint allows you to add new credentials or update existing ones. All credentials are encrypted and securely stored.
Credentials are sensitive data. Ensure you’re using secure connections and keep your API keys safe.

​
Endpoint

PUT https://api.toolrouter.ai/v1/stacks/{stack_id}/servers/{server_id}/credentials

​
Authentication

This endpoint requires an API key. Include it in the Authorization header: 
Authorization: Bearer YOUR_API_KEY

​
Path Parameters

​
stack_id
string
required
The unique identifier of the stack containing the server
​
server_id
string
required
The unique identifier of the server to update credentials for

​
Request Body

​
credentials
object
required
Object containing credential field IDs as keys and their values as values

​
Response

​
message
string
Confirmation message indicating credentials were updated successfully

​
Example Request

​
Configure Gmail Credentials

curl -X PUT "https://api.toolrouter.ai/v1/stacks/stack_123e4567-e89b-12d3-a456-426614174000/servers/gmail/credentials" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "credentials": {
      "gmail_oauth_token": "ya29.a0AfH6SMC...",
      "gmail_client_id": "123456789-abcdef.apps.googleusercontent.com",
      "gmail_client_secret": "GOCSPX-abc123def456",
      "gmail_signature": "Best regards,\nJohn Doe"
    }
  }'

​
Configure Linear Credentials

curl -X PUT "https://api.toolrouter.ai/v1/stacks/stack_123e4567-e89b-12d3-a456-426614174000/servers/linear/credentials" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "credentials": {
      "linear_api_key": "lin_api_abc123def456789"
    }
  }'

​
Update Specific Credentials

# Update only the OAuth token, leaving other credentials unchanged
curl -X PUT "https://api.toolrouter.ai/v1/stacks/stack_123e4567-e89b-12d3-a456-426614174000/servers/gmail/credentials" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "credentials": {
      "gmail_oauth_token": "ya29.a0AfH6SMC_new_token..."
    }
  }'

​
Example Response

{
  "message": "Credentials updated successfully"
}

​
Security Features

​
Encryption

  • All credentials are encrypted using industry-standard encryption before storage
  • Credentials are never stored in plain text
  • Encryption keys are managed separately from the stored credentials

​
Access Control

  • Credentials are isolated per user and stack
  • Only the stack owner can view or modify credentials
  • API key authentication ensures secure access

​
Audit Trail

  • All credential updates are logged for security monitoring
  • Changes can be tracked for compliance requirements

​
Credential Management Best Practices

​
Secure Handling

import os
import requests

# Use environment variables for sensitive data
headers = {
    "Authorization": f"Bearer {os.getenv('TOOLROUTER_API_KEY')}",
    "Content-Type": "application/json"
}

data = {
    "credentials": {
        "gmail_oauth_token": os.getenv('GMAIL_OAUTH_TOKEN'),
        "gmail_client_secret": os.getenv('GMAIL_CLIENT_SECRET')
    }
}

# Never log or print credential values
response = requests.put(endpoint_url, headers=headers, json=data)

​
Regular Rotation

  • Rotate credentials periodically for security
  • Update credentials immediately if they may have been compromised
  • Use this endpoint to update credentials when they expire

​
Validation

After updating credentials, verify they work: 
# Update credentials
update_response = requests.put(credentials_endpoint, headers=headers, json=credential_data)

# Check status
status_response = requests.get(f"https://api.toolrouter.ai/v1/stacks/{stack_id}/servers/{server_id}/credentials", headers=headers)
status = status_response.json()

# Test with a simple tool call
if status["required_credentials_added"]:
    # Try invoking a tool to verify credentials work
    tool_response = requests.post(f"https://api.toolrouter.ai/v1/stacks/{stack_id}/tools/{tool_id}/invoke", 
                                headers=headers, json=test_input)

​
Error Responses

​
400 Bad Request
Invalid credential data or format
{
  "detail": "Invalid credential format"
}
​
401 Unauthorized
Invalid or missing API key
{
  "detail": "Unauthorized"
}
​
404 Not Found
Stack, server, or server not found in stack
{
  "detail": "Stack not found"
}

{
  "detail": "Server gmail not found"
}
​
429 Too Many Requests
Rate limit exceeded
{
  "detail": "Too many requests"
}
​
500 Internal Server Error
Server error occurred
{
  "detail": "Failed to update credentials"
}

​
Next Steps

After updating credentials:
  1. Verify status: Use Get Credentials Status to confirm all required credentials are added
  2. Test functionality: Use Invoke Tool to verify tools work with the new credentials
  3. Monitor usage: Check that your applications can successfully use the tools with the updated credentials