Update Credentials

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

string

required

The unique identifier of the stack containing the server

string

required

The unique identifier of the server to update credentials for

Request Body

object

required

Object containing credential field IDs as keys and their values as values

Show Credential Fields

The keys should match the credential field IDs from the server definition. You can find these using the List Servers endpoint.Example credential fields:

gmail_oauth_token: OAuth token for Gmail API
gmail_client_id: Client ID for Gmail OAuth
gmail_client_secret: Client secret for Gmail OAuth
linear_api_key: API key for Linear integration

Response

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"
    }
  }'

import requests

headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}

data = {
    "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"
    }
}

response = requests.put(
    "https://api.toolrouter.ai/v1/stacks/stack_123e4567-e89b-12d3-a456-426614174000/servers/gmail/credentials",
    headers=headers,
    json=data
)

result = response.json()

const response = await fetch('https://api.toolrouter.ai/v1/stacks/stack_123e4567-e89b-12d3-a456-426614174000/servers/gmail/credentials', {
  method: 'PUT',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    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"
    }
  })
});

const result = await response.json();

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"
    }
  }'

import requests

headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}

data = {
    "credentials": {
        "linear_api_key": "lin_api_abc123def456789"
    }
}

response = requests.put(
    "https://api.toolrouter.ai/v1/stacks/stack_123e4567-e89b-12d3-a456-426614174000/servers/linear/credentials",
    headers=headers,
    json=data
)

result = response.json()

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..."
    }
  }'

import requests

headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}

# Update only specific credentials
data = {
    "credentials": {
        "gmail_oauth_token": "ya29.a0AfH6SMC_new_token..."
    }
}

response = requests.put(
    "https://api.toolrouter.ai/v1/stacks/stack_123e4567-e89b-12d3-a456-426614174000/servers/gmail/credentials",
    headers=headers,
    json=data
)

result = response.json()

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

Invalid credential data or format

{
  "detail": "Invalid credential format"
}

Invalid or missing API key

{
  "detail": "Unauthorized"
}

Stack, server, or server not found in stack

{
  "detail": "Stack not found"
}

{
  "detail": "Server gmail not found"
}

Rate limit exceeded

{
  "detail": "Too many requests"
}

Server error occurred

{
  "detail": "Failed to update credentials"
}

Next Steps

After updating credentials:

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

API Documentation

Stack Specific Endpoints

Account Management API

Stack Management

Server Management

Credentials Management

Tools Management

SDK

Overview

Endpoint

Authentication

Path Parameters

Request Body

Response

Example Request

Configure Gmail Credentials

Configure Linear Credentials

Update Specific Credentials

Example Response

Security Features

Encryption

Access Control

Audit Trail

Credential Management Best Practices

Secure Handling

Regular Rotation

Validation

Error Responses

Next Steps

​Overview

​Endpoint

​Authentication

​Path Parameters

​Request Body

​Response

​Example Request

​Configure Gmail Credentials

​Configure Linear Credentials

​Update Specific Credentials

​Example Response

​Security Features

​Encryption

​Access Control

​Audit Trail

​Credential Management Best Practices

​Secure Handling

​Regular Rotation

​Validation

​Error Responses

​Next Steps

Overview

Endpoint

Authentication

Path Parameters

Request Body

Response

Example Request

Configure Gmail Credentials

Configure Linear Credentials

Update Specific Credentials

Example Response

Security Features

Encryption

Access Control

Audit Trail

Credential Management Best Practices

Secure Handling

Regular Rotation

Validation

Error Responses

Next Steps