API FAQs
Getting started
Q: How do I get access to the APIs?
A: Click Sign Up and register with SSO (Microsoft Entra ID / Google / GitHub). After sign-in, create an Application in the portal and subscribe to a Plan to receive credentials (API key and/or OAuth 2.0 client).
Q: Is there a sandbox?
A: Yes. We provide an Isolated Sandbox with realistic sample data. Use it for integration and QA before requesting Production promotion.
Q: Where’s the OpenAPI/Swagger?
A: Every API has an OpenAPI 3.x spec on its detail page. You can also download a bundle or import directly into Postman.
Q: Do you have SDKs?
A: We publish lightweight SDKs for JavaScript/TypeScript, .NET, and Python. They’re generated from OpenAPI and versioned alongside the APIs.
Authentication & authorization
Q: Which auth methods are supported?
A: We support OAuth 2.0 (Client Credentials and Authorization Code) and API keys for selected endpoints. Some partner flows support JWT Bearer.
Q: How do I create OAuth credentials?
A: In My Apps → Create Application, select OAuth 2.0, then note your Client ID and Client Secret. Configure allowed Redirect URIs for user-delegated flows.
Q: Example: how do I get a token (Client Credentials)?
curl -X POST https://auth.example.com/oauth2/token \ -d 'grant_type=client_credentials&client_id=YOUR_ID&client_secret=YOUR_SECRET&scope=api.read'Use the returned access_token in the Authorization: Bearer <token> header.
Q: Do you support RBAC?
A: Yes. Access is role-based (Admin, Developer, Tester) and can be scoped to teams/projects. Requests beyond your scope will return 403.
Q: Can we rotate credentials?
A: Yes. You can create a new key/secret, validate it, then revoke the old one. We’ll warn you ahead of expirations.
Rate limits, quotas, and performance
Q: What are the limits?
A: Limits depend on your plan. We send standard headers:
X-RateLimit-Limit,X-RateLimit-Remaining,X-RateLimit-ResetRetry-Afteron 429 responses
Q: What should my retry strategy be?
A: Use exponential backoff with jitter for 429/5xx, respect Retry-After, and implement idempotency (see below).
Q: Do you support global edge delivery?
A: Yes—traffic is routed to the nearest region where available. For strict residency, pin to a region in your subscription request.
Requests, responses, and errors
Q: What’s the standard error shape?
A:
{ "traceId": "b123...", "code": "RESOURCE_NOT_FOUND", "message": "Part not found for the given id", "details": [{ "field": "id", "issue": "unknown" }] }Keep traceId when contacting support.
Q: What status codes should I expect?
A: 2xx success, 400 validation, 401/403 auth/permission, 404 not found, 409 conflict, 429 throttled, 5xx transient error.
Q: What’s the max payload size?
A: Default 10 MB request/response. For larger exports, use async jobs or paginated downloads.
Pagination, filtering, and sorting
Q: How do I paginate?
A: Most list endpoints use cursor-based pagination:
GET /items?limit=100&cursor=eyJwYWdlIjoyfQ== Link: <...cursor=abc...>; rel="next"Some endpoints may use page/pageSize—check the OpenAPI for each API.
Q: Can I filter and sort?
A: Yes. Use query params like ?filter=status:eq:ACTIVE,region:eq:NA&sort=-updatedAt.
Versioning, deprecations, and change management
Q: How are versions managed?
A: We version in the URL (/v1/) and/or header Accept: application/vnd.example.v1+json. Minor changes are backward compatible.
Q: How will I learn about breaking changes?
A: The Changelog and News sections announce changes. Breaking changes include a deprecation window (e.g., 90–180 days) plus email notices to app owners.
Q: Can I stay on an old version?
A: Yes during the deprecation period. After that, calls may be blocked. We’ll provide migration guides and test cases.
Environments & release management
Q: Do you offer mock servers?
A: Yes. Each API publishes a mock based on the OpenAPI examples for early integration and contract testing.
Security & compliance
Q: Are you GDPR/CCPA compliant?
A: Yes. We honor data-subject rights, data minimization, and retention policies. See our Privacy and DPA links.
Q: Do you support IP allow-listing?
A: Yes. You can request static egress IPs and submit allow-lists per environment.
Q: How are secrets handled?
A: Secrets are encrypted at rest and in transit. Server-side secrets are managed in a secure vault with strict RBAC and audit logs.
Observability & incidents
Q: How do I monitor usage?
A: Use the Usage Analytics Dashboard in the portal (Power BI) for calls, latency, errors, and spend. Export raw logs if you need deeper analysis.
Q: Where can I see uptime?
A: Check the Status Page for real-time availability and historical incidents. Subscribe to incident notifications.
Q: What’s the SLA?
A: Standard plans include 99.9% API availability; higher tiers offer enhanced SLAs. See your plan details.
Commercials & plans
Q: How does pricing work?
A: Plans define quota, rate limits, and (if applicable) per-call or bundle pricing. Overages throttle by default; paid plans can add burst credits.
Q: Can I change plans later?
A: Yes—upgrades apply immediately; downgrades take effect at the next billing cycle.
Webhooks & events (if provided)
Q: Do you support webhooks?
A: Yes for selected domains. Register a URL, verify ownership via HMAC-SHA256 signature header, and handle retries with idempotency.
Q: How do I verify webhook signatures?
A: Recompute HMAC(secret, payload) and compare to X-Signature. Reject if timestamps are older than your tolerance window.
Support & contact
Q: How do I open a ticket?
A: Use Support → New Ticket in the portal (routes to ASK Tickets / Zoho). Include your traceId, API name, environment, and a minimal repro.
Q: Do you have office hours?
A: Yes—see the Community page for office hours and upcoming tech shares.
Q: Where can I request a new API or scope?
A: Use Request Access on the API page or submit a Feature Request form with your use case and expected volumes.