Custom Credential Service

Skyvern supports integrating with custom HTTP APIs for credential management, allowing you to use your existing credential infrastructure instead of third-party services.

Overview

The custom credential service feature enables Skyvern to store and retrieve credentials from external HTTP APIs. This is perfect for organizations that:

• Have existing credential management systems
• Need to maintain credentials in their own infrastructure
• Want to integrate with proprietary credential vaults
• Require custom authentication flows

API Contract

Your custom credential service must implement these HTTP endpoints:

Create Credential

1
POST {API_BASE_URL}
2
Authorization: Bearer {API_TOKEN}
3
Content-Type: application/json
4
5
{
6
  "name": "My Credential",
7
  "type": "password",
8
  "username": "user@example.com",
9
  "password": "secure_password",
10
  "totp": "JBSWY3DPEHPK3PXP",
11
  "totp_type": "authenticator"
12
}

Response:

1
{
2
  "id": "cred_123456"
3
}

Get Credential

1
GET {API_BASE_URL}/{credential_id}
2
Authorization: Bearer {API_TOKEN}

Response:

1
{
2
  "type": "password",
3
  "username": "user@example.com",
4
  "password": "secure_password",
5
  "totp": "JBSWY3DPEHPK3PXP",
6
  "totp_type": "authenticator"
7
}

Delete Credential

1
DELETE {API_BASE_URL}/{credential_id}
2
Authorization: Bearer {API_TOKEN}

Response: HTTP 200 (empty body acceptable)

Configuration

Environment Variables (Self-hosted)

Set these environment variables in your .env file:

$
CREDENTIAL_VAULT_TYPE=custom
>
CUSTOM_CREDENTIAL_API_BASE_URL=https://credentials.company.com/api/v1/credentials
>
CUSTOM_CREDENTIAL_API_TOKEN=your_api_token_here

Organization Configuration (Cloud)

Use the Skyvern API to configure per-organization:

1
POST /api/v1/credentials/custom_credential/create
2
Authorization: Bearer {SKYVERN_API_KEY}
3
Content-Type: application/json
4
5
{
6
  "config": {
7
    "api_base_url": "https://credentials.company.com/api/v1/credentials",
8
    "api_token": "your_api_token_here"
9
  }
10
}

UI Configuration

1. Navigate to Settings → Custom Credential Service
2. Enter your API Base URL and API Token
3. Click Test Connection to verify connectivity
4. Click Update Configuration to save

Example Implementation

Here’s a minimal example using FastAPI:

1
from fastapi import FastAPI, HTTPException, Depends, Header
2
from pydantic import BaseModel
3
from typing import Optional
4
import uuid
5
6
app = FastAPI()
7
8
# In-memory storage (use a real database in production)
9
credentials_store = {}
10
11
class CreateCredentialRequest(BaseModel):
12
    name: str
13
    type: str  # "password" or "credit_card"
14
    username: Optional[str] = None
15
    password: Optional[str] = None
16
    totp: Optional[str] = None
17
    totp_type: Optional[str] = None
18
19
class CredentialResponse(BaseModel):
20
    id: str
21
22
def verify_token(authorization: str = Header(...)):
23
    if not authorization.startswith("Bearer "):
24
        raise HTTPException(401, "Invalid authorization header")
25
26
    token = authorization.split("Bearer ")[1]
27
    if token != "your_expected_api_token":
28
        raise HTTPException(401, "Invalid API token")
29
30
@app.post("/api/v1/credentials", response_model=CredentialResponse)
31
async def create_credential(
32
    request: CreateCredentialRequest,
33
    _: None = Depends(verify_token)
34
):
35
    credential_id = f"cred_{uuid.uuid4().hex[:12]}"
36
    credentials_store[credential_id] = request.model_dump()
37
    return CredentialResponse(id=credential_id)
38
39
@app.get("/api/v1/credentials/{credential_id}")
40
async def get_credential(
41
    credential_id: str,
42
    _: None = Depends(verify_token)
43
):
44
    if credential_id not in credentials_store:
45
        raise HTTPException(404, "Credential not found")
46
    return credentials_store[credential_id]
47
48
@app.delete("/api/v1/credentials/{credential_id}")
49
async def delete_credential(
50
    credential_id: str,
51
    _: None = Depends(verify_token)
52
):
53
    if credential_id not in credentials_store:
54
        raise HTTPException(404, "Credential not found")
55
    del credentials_store[credential_id]
56
    return {"status": "deleted"}

Security Considerations

• API tokens are stored encrypted in the database
• Bearer tokens are transmitted over HTTPS only
• Frontend masks sensitive tokens in the UI
• API credentials are never logged in plaintext
• Implement proper rate limiting and authentication in your API

Troubleshooting

Connection Test Fails

1. Verify API base URL is correct and accessible
2. Check that API token is valid
3. Check firewall and network connectivity
4. Note: Connection test only verifies basic connectivity - 404/405 responses are considered successful if the server is reachable

Credentials Not Created

1. Review API logs for authentication errors
2. Verify request format matches expected schema
3. Ensure API returns id in response

Environment Configuration Not Working

1. Restart Skyvern after setting environment variables
2. Verify CREDENTIAL_VAULT_TYPE=custom is set
3. Check both URL and token are provided

Limitations

• Connection testing verifies network connectivity and basic API reachability but not full endpoint implementation
• API must support all required endpoints (no partial implementation)
• Token rotation requires manual reconfiguration
• No built-in credential synchronization between vaults