Terminal
Terminal/Skill
Sets up Sinch API credentials and OAuth2, Basic, signing, or API key auth, and fixes 401 and 403 errors.
By Sinch
Works with
npx skills add sinch/skills --skill sinch-authenticationCross-cutting skill that covers credential setup and authentication for all Sinch APIs. Determines the correct auth model, provides curl examples, SDK init code, and troubleshooting for common auth errors.
Policy gate
sinch-shared-policy@5(sha256:4864cf0fa8d6): The policy digest below is binding as written. Before implementation or live execution, read the full shared Sinch policy once per conversation — skip it if this exact ID/version/fingerprint is already loaded; read it if the version is newer or the fingerprint differs. This skill's canonical operation routes live in its Agent Instructions and Links sections.
Sinch policy digest (binding):
If the user hasn't specified which Sinch product they're integrating, ask first — the auth model depends on the product. Use the decision table in Step 1 to route to the correct credentials.
This skill has two kinds of content with UNEQUAL reliability. Follow this precedence:
developers.sinch.com (AUTHORITATIVE). The .md doc links in
this skill are the single source of truth for exact request/response schemas, field
names and nesting, enum values, signature/auth schemes, and limits. Before writing
code that constructs a payload, verifies a signature, or parses a callback/response,
fetch the specific linked doc and confirm the exact shape there. Fetching first-party
developers.sinch.com URLs is permitted by the Security/URL policy. Never invent, guess, or pattern-extrapolate a documentation URL — only fetch doc URLs written verbatim in this skill or reached by following a link on a page you already fetched; a trusted domain does not make a guessed path real.Quick rule: writing code → load the doc. Never cite an exact field, header, enum, or encoding you only saw in a summary.
Determine which model applies based on the Sinch product:
| Auth Model | Products | Credentials Needed |
|---|---|---|
| Project-scoped (Basic or OAuth2) | Conversation API, Numbers, Fax, EST, 10DLC, Number Lookup, Provisioning | Project ID + Key ID + Key Secret |
| Application-scoped (Basic or Signed) | Voice API, Verification API, In-App Calling SDKs | Application Key + Application Secret |
| API key | Mailgun | API Key (username is literal api) |
Voice/Verification credentials are a separate credential set from project Access Keys (different dashboard pages and auth models). In multi-product SDK clients, you may provide both sets together, but do not substitute one set for the other.
Store Key Secrets securely — they are shown only once at creation.
Load credentials into environment variables before making API calls — never embed them directly in commands or code:
# Project-scoped APIs (Conversation, Numbers, Fax, etc.)
export SINCH_PROJECT_ID="your-project-id"
export SINCH_KEY_ID="your-key-id"
export SINCH_KEY_SECRET="your-key-secret"
# Application-scoped APIs (Voice, Verification)
export SINCH_APP_KEY="your-application-key"
export SINCH_APP_SECRET="your-application-secret"
# Mailgun
export MAILGUN_API_KEY="your-mailgun-api-key"
export MAILGUN_DOMAIN="your-domain.com"
OAuth2 (recommended) — Exchange credentials for a bearer token:
curl -X POST \
https://auth.sinch.com/oauth2/token \
-u "$SINCH_KEY_ID:$SINCH_KEY_SECRET" \
-d grant_type=client_credentials
(Summary only — confirm exact names/encoding/enums against the authoritative Sinch Docs doc before implementing.)
The response JSON contains an access_token field — this is the JWT to use as the bearer token:
{ "access_token": "eyJ...", "token_type": "bearer", "expires_in": 3600 }
Do not mint your own JWT. The
access_tokenabove is issued and signed by Sinch's auth server. Locally-signed JWTs (e.g.jsonwebtoken.sign({ iss: keyId }, keySecret, { algorithm: "HS256" })) will be rejected with HTTP 401 by every Sinch API. Always POSTgrant_type=client_credentialsto the token endpoint and use the returnedaccess_tokenverbatim.
Use it in subsequent requests (expires in 3600s):
curl -X GET \
"https://numbers.api.sinch.com/v1/projects/$SINCH_PROJECT_ID/activeNumbers" \
-H "Authorization: Bearer $SINCH_ACCESS_TOKEN"
The token endpoint https://auth.sinch.com/oauth2/token works for all project-scoped APIs, including regional ones like Conversation and Template Management.
Basic auth (quick testing only) — Supported but not recommended for production (heavily rate-limited). Pass Key ID as username and Key Secret as password:
curl -X GET \
"https://numbers.api.sinch.com/v1/projects/$SINCH_PROJECT_ID/activeNumbers" \
-u "$SINCH_KEY_ID:$SINCH_KEY_SECRET"
Always prefer OAuth2 bearer tokens for production workloads — Basic auth has lower rate limits and exposes credentials in every request.
Use Basic auth (prototyping) — Application Key as username, Application Secret as password:
curl -X POST \
"https://calling.api.sinch.com/calling/v1/callouts" \
-u "$SINCH_APP_KEY:$SINCH_APP_SECRET"
Or use HMAC Signed Requests (production) — see signing algorithm docs:
Verification API also supports Public Authentication (weak, client-side SDK only).
curl -X GET \
"https://api.mailgun.net/v3/$MAILGUN_DOMAIN/messages" \
-s --user "api:$MAILGUN_API_KEY"
For SDK installation and client initialization, see the sinch-sdks skill.
| Error | Cause | Fix |
|---|---|---|
401 Unauthorized on Conversation/Numbers API | Wrong credentials or expired token | Verify Key ID from Access Keys and use the Key Secret saved at creation time; if the secret was lost, create a new Access Key and re-request an OAuth2 token. Also inspect the WWW-Authenticate response header for details (for example, invalid token, expired token, or invalid client). |
401 Invalid Signature on Voice/Verification | Wrong Application Key/Secret or signing error | Verify app credentials from Voice > Apps; ensure HMAC signing matches the algorithm spec |
| OAuth2 token works for Numbers but fails for Conversation | Wrong API base URL region | Ensure the API base URL matches the app's region (e.g., eu.conversation.api.sinch.com for EU apps) |
403 Forbidden | Key doesn't have access to this project/product | Check Access Key scope in dashboard; ensure correct Project ID |
Dashboard links below require authentication and are intended for human operators. Agents should rely on public docs for procedural guidance and treat dashboard URLs as navigational references only.
Authenticated Console Links (human operators):
Public Documentation Links (agent-friendly):