Senhasegura
Skill Type: Library/API Reference (Type 1) + Data Fetching (Type 3).
Practical integration guide for the senhasegura (Segura) Privileged Access Management platform. Covers A2A OAuth 2.0 auth, PAM Core credential and SSH key APIs, DevOps Secret Manager (DSM) for CI/CD, External Secrets Operator for Kubernetes, MySafe, and an opt-in MCP server.
Voice Notification (on invocation)
curl -s -X POST http://localhost:31337/notify \
-H "Content-Type: application/json" \
-d '{"message": "Running the Senhasegura skill"}' \
> /dev/null 2>&1 &
Workflow Routing
| Trigger |
Workflow |
| "set up A2A", "create senhasegura application", first-time OAuth client |
Workflows/SetupA2A.md |
| "sync secrets to Kubernetes", ESO + senhasegura DSM |
Workflows/SyncKubernetesSecrets.md |
| "rotate password", schedule rotation, Executions module |
Workflows/RotatePasswords.md |
"fetch secrets in pipeline", DSM runb in CI/CD |
Workflows/InjectCiCdSecrets.md |
| "register SSH key", manage SSH key rotation |
Workflows/RegisterSshKey.md |
Reference Routing
| Topic |
File |
| OAuth 2.0 flow, A2A application creation, token caching |
Authentication.md |
| PAM Core endpoints — credentials, custody, SSH keys |
PamApi.md |
| DSM CLI, runb, mapping.json, External Secrets Operator |
Dsm.md |
| MySafe, Python/TypeScript clients, CI/CD pipeline templates |
Integrations.md |
| Errors, debug mode, rate limits, common failure modes |
Troubleshooting.md |
| MCP server (opt-in Claude Code integration) |
References/McpIntegration.md + Tools/SenhaseguraMcpServer.ts |
| Legacy OAuth 1.0 reference |
References/OAuth1Legacy.md |
| Python SDK reference (PAI standard is TypeScript+Bun) |
References/PythonSdk.md |
Gotchas
These are non-obvious senhasegura behaviors that bite users. Add new entries as they're discovered.
| # |
Gotcha |
| 1 |
GET /iso/coe/senha?credentialId=N auto-locks the credential into custody. You MUST DELETE /iso/pam/credential/custody/N after, or the credential is held until manual release. Concurrent jobs deadlock on the second fetch. |
| 2 |
OAuth 2.0 access token TTL is 3600s. Cache and refresh at expiry minus 60s buffer, not on 401 retry. 401 retry storms hammer the IDP and trigger rate limits. |
| 3 |
/iso/coe/senha is the legacy A2A v1 password retrieval path; /api/pam/credential/{id} returns metadata only. The legacy path is current — do not refactor it away. |
| 4 |
A2A authorization IP restriction is matched against the HTTP source IP as seen by senhasegura — for Kubernetes, that's the egress NAT, not the pod IP. Whitelist the cluster egress. ESO failures surface as a generic "could not get provider client". |
| 5 |
DSM runb writes secrets to .runb.vars in the current working directory. If cwd is the repo root, it can be accidentally committed. Always run from a tmpdir or set SENHASEGURA_SECRETS_FILE=/tmp/runb.$$.vars. |
| 6 |
External Secrets Operator provider key is senhasegura (lowercase) and module is DSM (uppercase). Mixed case = silent provider-not-found; ESO just fails to reconcile with no clear error. |
| 7 |
dsm runb --tool-name <X> accepts github, azure-devops, gitlab, linux. Using linux outside Linux containers (Windows runners, unspecified) prevents masking of secret values in CI logs — secrets leak into log output. |
| 8 |
The Python and TypeScript clients in References/ do not auto-release custody on raw getPassword. Use the provided withPassword(...) / password_context(...) helpers, which wrap try/finally. |
| 9 |
The token endpoint is /iso/oauth2/token — note /iso/, not /api/. Senhasegura's path scheme mixes /iso/ (legacy/console) and /api/ (newer REST) inconsistently. |
| 10 |
Most enterprise installs use internal CAs. Reach for ignoreSslCertificate: true / SENHASEGURA_INSECURE: true only for local debugging. The proper path is mounting the CA bundle into ESO via the ca field. |
Quick Reference
# 1. Get token (1h TTL)
TOKEN=$(curl -s -X POST "$SENHASEGURA_URL/iso/oauth2/token" \
-d "grant_type=client_credentials" \
-d "client_id=$SENHASEGURA_CLIENT_ID" \
-d "client_secret=$SENHASEGURA_CLIENT_SECRET" | jq -r '.access_token')
# 2. List credentials
curl -H "Authorization: Bearer $TOKEN" "$SENHASEGURA_URL/api/pam/credential"
# 3. Get password (auto-locks custody — see Gotcha #1)
curl -H "Authorization: Bearer $TOKEN" \
"$SENHASEGURA_URL/iso/coe/senha?credentialId=123"
# 4. Release custody (REQUIRED after step 3)
curl -X DELETE -H "Authorization: Bearer $TOKEN" \
"$SENHASEGURA_URL/iso/pam/credential/custody/123"
# 5. DSM secret fetch via CLI
dsm runb --tool-name github \
--application my-app --system production --environment prod
source .runb.vars && rm -f .runb.vars
Environment Variables
SENHASEGURA_URL="https://senhasegura.example.com"
SENHASEGURA_CLIENT_ID="oauth2-client-id"
SENHASEGURA_CLIENT_SECRET="oauth2-client-secret"
# DSM CLI optionals
SENHASEGURA_CONFIG_FILE="/path/to/config.yaml"
SENHASEGURA_MAPPING_FILE="/path/to/mapping.json"
SENHASEGURA_SECRETS_FILE="/tmp/runb.$$.vars" # don't write into repo root
SENHASEGURA_TIMEOUT="30"
# SENHASEGURA_INSECURE — local debug only; mount the CA bundle in prod
Documentation Links
Execution Log
Append after every workflow run:
echo '{"ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","skill":"Senhasegura","workflow":"WORKFLOW_USED","input":"8_WORD_SUMMARY","status":"ok|error","duration_s":SECONDS}' \
>> ~/.claude/PAI/MEMORY/SKILLS/execution.jsonl
1---2name: senhasegura3description: Senhasegura PAM platform integration — A2A OAuth 2.0, PAM Core credentials, SSH key rotation, DSM CLI for CI/CD, External Secrets Operator (Kubernetes), MySafe, and a runnable MCP server. USE WHEN senhasegura, segura, A2A application, DSM CLI, runb, MySafe, ExternalSecret + senhasegura, OAuth client_credentials for PAM, credential custody release, /iso/coe/senha endpoint, SCIM provisioning. NOT FOR HashiCorp Vault, AWS Secrets Manager, Azure Key Vault, GCP Secret Manager, 1Password, or generic OAuth 2.0 flows (use those directly).4---5
6# Senhasegura
7
8**Skill Type:** Library/API Reference (Type 1) + Data Fetching (Type 3).
9
10Practical integration guide for the senhasegura (Segura) Privileged Access Management platform. Covers A2A OAuth 2.0 auth, PAM Core credential and SSH key APIs, DevOps Secret Manager (DSM) for CI/CD, External Secrets Operator for Kubernetes, MySafe, and an opt-in MCP server.
11
12## Voice Notification (on invocation)
13
14```bash
15curl -s -X POST http://localhost:31337/notify \
16 -H "Content-Type: application/json" \
17 -d '{"message": "Running the Senhasegura skill"}' \
18 > /dev/null 2>&1 &
19```
20
21## Workflow Routing
22
23| Trigger | Workflow |
24|---------|----------|
25| "set up A2A", "create senhasegura application", first-time OAuth client | `Workflows/SetupA2A.md` |
26| "sync secrets to Kubernetes", ESO + senhasegura DSM | `Workflows/SyncKubernetesSecrets.md` |
27| "rotate password", schedule rotation, Executions module | `Workflows/RotatePasswords.md` |
28| "fetch secrets in pipeline", DSM `runb` in CI/CD | `Workflows/InjectCiCdSecrets.md` |
29| "register SSH key", manage SSH key rotation | `Workflows/RegisterSshKey.md` |
30
31## Reference Routing
32
33| Topic | File |
34|-------|------|
35| OAuth 2.0 flow, A2A application creation, token caching | `Authentication.md` |
36| PAM Core endpoints — credentials, custody, SSH keys | `PamApi.md` |
37| DSM CLI, runb, mapping.json, External Secrets Operator | `Dsm.md` |
38| MySafe, Python/TypeScript clients, CI/CD pipeline templates | `Integrations.md` |
39| Errors, debug mode, rate limits, common failure modes | `Troubleshooting.md` |
40| MCP server (opt-in Claude Code integration) | `References/McpIntegration.md` + `Tools/SenhaseguraMcpServer.ts` |
41| Legacy OAuth 1.0 reference | `References/OAuth1Legacy.md` |
42| Python SDK reference (PAI standard is TypeScript+Bun) | `References/PythonSdk.md` |
43
44## Gotchas
45
46These are non-obvious senhasegura behaviors that bite users. Add new entries as they're discovered.
47
48| # | Gotcha |
49|---|--------|
50| 1 | `GET /iso/coe/senha?credentialId=N` **auto-locks the credential into custody.** You MUST `DELETE /iso/pam/credential/custody/N` after, or the credential is held until manual release. Concurrent jobs deadlock on the second fetch. |
51| 2 | OAuth 2.0 access token TTL is 3600s. Cache and refresh **at expiry minus 60s buffer**, not on 401 retry. 401 retry storms hammer the IDP and trigger rate limits. |
52| 3 | `/iso/coe/senha` is the **legacy A2A v1 password retrieval path**; `/api/pam/credential/{id}` returns metadata only. The legacy path is current — do not refactor it away. |
53| 4 | A2A authorization IP restriction is matched against the **HTTP source IP as seen by senhasegura** — for Kubernetes, that's the egress NAT, not the pod IP. Whitelist the cluster egress. ESO failures surface as a generic "could not get provider client". |
54| 5 | DSM `runb` writes secrets to `.runb.vars` in the **current working directory**. If cwd is the repo root, it can be accidentally committed. Always run from a tmpdir or set `SENHASEGURA_SECRETS_FILE=/tmp/runb.$$.vars`. |
55| 6 | External Secrets Operator provider key is `senhasegura` (lowercase) and module is `DSM` (uppercase). Mixed case = silent provider-not-found; ESO just fails to reconcile with no clear error. |
56| 7 | `dsm runb --tool-name <X>` accepts `github`, `azure-devops`, `gitlab`, `linux`. Using `linux` outside Linux containers (Windows runners, unspecified) prevents masking of secret values in CI logs — secrets leak into log output. |
57| 8 | The Python and TypeScript clients in `References/` do **not** auto-release custody on raw `getPassword`. Use the provided `withPassword(...)` / `password_context(...)` helpers, which wrap try/finally. |
58| 9 | The token endpoint is `/iso/oauth2/token` — note `/iso/`, not `/api/`. Senhasegura's path scheme mixes `/iso/` (legacy/console) and `/api/` (newer REST) inconsistently. |
59| 10 | Most enterprise installs use internal CAs. Reach for `ignoreSslCertificate: true` / `SENHASEGURA_INSECURE: true` only for local debugging. The proper path is mounting the CA bundle into ESO via the `ca` field. |
60
61## Quick Reference
62
63```bash
64# 1. Get token (1h TTL)
65TOKEN=$(curl -s -X POST "$SENHASEGURA_URL/iso/oauth2/token" \
66 -d "grant_type=client_credentials" \
67 -d "client_id=$SENHASEGURA_CLIENT_ID" \
68 -d "client_secret=$SENHASEGURA_CLIENT_SECRET" | jq -r '.access_token')
69
70# 2. List credentials
71curl -H "Authorization: Bearer $TOKEN" "$SENHASEGURA_URL/api/pam/credential"
72
73# 3. Get password (auto-locks custody — see Gotcha #1)
74curl -H "Authorization: Bearer $TOKEN" \
75 "$SENHASEGURA_URL/iso/coe/senha?credentialId=123"
76
77# 4. Release custody (REQUIRED after step 3)
78curl -X DELETE -H "Authorization: Bearer $TOKEN" \
79 "$SENHASEGURA_URL/iso/pam/credential/custody/123"
80
81# 5. DSM secret fetch via CLI
82dsm runb --tool-name github \
83 --application my-app --system production --environment prod
84source .runb.vars && rm -f .runb.vars
85```
86
87## Environment Variables
88
89```bash
90SENHASEGURA_URL="https://senhasegura.example.com"
91SENHASEGURA_CLIENT_ID="oauth2-client-id"
92SENHASEGURA_CLIENT_SECRET="oauth2-client-secret"
93
94# DSM CLI optionals
95SENHASEGURA_CONFIG_FILE="/path/to/config.yaml"
96SENHASEGURA_MAPPING_FILE="/path/to/mapping.json"
97SENHASEGURA_SECRETS_FILE="/tmp/runb.$$.vars" # don't write into repo root
98SENHASEGURA_TIMEOUT="30"
99# SENHASEGURA_INSECURE — local debug only; mount the CA bundle in prod
100```
101
102## Documentation Links
103
104- [Official documentation](https://docs.senhasegura.io/docs)
105- [A2A module](https://docs.senhasegura.io/docs/a2a)
106- [DSM module](https://docs.senhasegura.io/docs/devops-secret-manager)
107- [PAM Core API reference](https://docs.senhasegura.io/docs/api-a2a-pam-core)
108- [DSM CLI on GitHub](https://github.com/senhasegura/dsmcli)
109- [External Secrets Operator — senhasegura provider](https://external-secrets.io/latest/provider/senhasegura-dsm/)
110
111## Execution Log
112
113Append after every workflow run:
114
115```bash
116echo '{"ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","skill":"Senhasegura","workflow":"WORKFLOW_USED","input":"8_WORD_SUMMARY","status":"ok|error","duration_s":SECONDS}' \
117 >> ~/.claude/PAI/MEMORY/SKILLS/execution.jsonl
118```
julianobarbosa