{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"FAQ & Troubleshooting"},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"faq--troubleshooting","__idx":0},"children":["FAQ & Troubleshooting"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Answers to the questions integrators most commonly hit against the Titan Public API."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"auth--login","__idx":1},"children":["Auth & login"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"how-do-i-get-a-token","__idx":2},"children":["How do I get a token?"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The API uses ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["OAuth 2.0 client credentials"]},". Create a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CLIENT_ID"]}," / ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CLIENT_SECRET"]}," pair from ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Connectors → APIs"]}," in the SecurityScorecard app, then exchange them at ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v1/oauth/token"]}," with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["grant_type=client_credentials"]},". Full walkthrough in ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/guides/getting-started"},"children":["Getting Started"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The same credentials work for both REST and ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/guides/mcp"},"children":["MCP"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"im-getting-401-unauthorized--why","__idx":3},"children":["I'm getting ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401 Unauthorized"]},". Why?"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401"]}," means the request was ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["not authenticated"]},". Common causes:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["No ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Authorization: Bearer …"]}," header on the request."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The bearer token is malformed (extra whitespace, missing ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Bearer "]}," prefix, or the header holds the raw ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CLIENT_SECRET"]}," instead of an access token)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The access token has expired — re-exchange your ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CLIENT_ID"]}," / ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CLIENT_SECRET"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The credential has been deleted or rotated. Confirm it still exists on the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Connectors → APIs"]}," page."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"im-getting-403-forbidden--why","__idx":4},"children":["I'm getting ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["403 Forbidden"]},". Why?"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["403"]}," means the token was ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["valid"]}," but the caller is ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["not permitted"]},". Common causes:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The credential lacks the required scope. Read-only calls need ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Read security findings"]},"; mutating calls additionally need ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Flag security findings"]},". Scopes are set when the credential is created — issue a new credential with the right scopes."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The token's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["org"]}," claim doesn't match the resource. Every credential is scoped to the organization that issued it."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"rate-limits","__idx":5},"children":["Rate limits"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"im-getting-429-too-many-requests--what-do-i-do","__idx":6},"children":["I'm getting ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["429 Too Many Requests"]},". What do I do?"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Honour the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Retry-After"]}," header — it tells you how many seconds to wait before retrying. If unavailable, fall back to ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["exponential backoff with jitter"]}," (base 1s, factor 2, cap 60s)."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Do ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["not"]}," retry immediately, and do ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["not"]}," rotate credentials or IPs to evade the limit — the counter is keyed by ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["organization"]},". See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/guides/usage-limits"},"children":["Usage Limits"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"do-mcp-and-rest-share-a-rate-limit-budget","__idx":7},"children":["Do MCP and REST share a rate-limit budget?"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The limits are ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["numerically identical"]}," but the counters are ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["independent"]}," — a burst on REST won't starve MCP or vice versa."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"how-do-i-get-higher-limits","__idx":8},"children":["How do I get higher limits?"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Contact your SecurityScorecard account team with your organization identifier, the endpoints you'll call, and whether traffic is steady or bursty. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/guides/usage-limits#getting-more-headroom"},"children":["Usage Limits"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"idempotency","__idx":9},"children":["Idempotency"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"i-retried-a-flag-action-and-got-a-conflict-what-does-that-mean","__idx":10},"children":["I retried a flag action and got a conflict. What does that mean?"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Flag actions are ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["idempotent by design"]},". A ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["409"]}," conflict means the resource is in a state that rejects the operation — for example, flagging something already resolved. Do not blindly retry a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["409"]},". Read ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error.code"]}," and either adjust the request or treat the current state as the accepted outcome. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/guides/errors#status-codes"},"children":["Errors"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"mcp-connector-setup","__idx":11},"children":["MCP connector setup"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"i-added-the-titan-mcp-connector-but-the-client-doesnt-call-it","__idx":12},"children":["I added the Titan MCP connector but the client doesn't call it."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Interactive AI clients don't always auto-invoke MCP tools from a generic prompt. Reliable fixes:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Name the tool explicitly: ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["\"Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GetObservations"]}," to list this week's CVE findings.\""]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Name the connector: ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["\"Using the Titan MCP connector, show me high-severity findings.\""]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Ask the client to list tools first: ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["\"List the tools available from the Titan MCP server, then answer …\""]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/guides/mcp#prompting-getting-the-client-to-call-titan-mcp"},"children":["MCP → Prompting"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"the-mcp-endpoint-returns-401-","__idx":13},"children":["The MCP endpoint returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Same causes as REST ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401"]}," above. MCP uses the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["same bearer token"]}," as REST."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"the-mcp-endpoint-returns-403-","__idx":14},"children":["The MCP endpoint returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["403"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The credential lacks the scope for the tool you invoked. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/guides/mcp#scopes"},"children":["MCP → Scopes"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"the-connector-connects-but-returns-no-data","__idx":15},"children":["The connector connects but returns no data."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The credential's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["org"]}," must match the organization whose data you expect — cross-org calls always return empty."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Confirm the tool actually ran by asking the client to show its tool-call trace."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"pagination","__idx":16},"children":["Pagination"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"how-do-i-know-ive-reached-the-end","__idx":17},"children":["How do I know I've reached the end?"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Cursor mode:"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["next_cursor"]}," is absent or empty. A short page is ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["not"]}," a reliable end-of-stream signal — always check ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["next_cursor"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Offset mode:"]}," the response contains zero rows."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/guides/pagination"},"children":["Pagination"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"the-cursor-stopped-working-after-a-while","__idx":18},"children":["The cursor stopped working after a while."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Cursors expire after ~24 hours. Restart from ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cursor=\"\""]}," and dedupe by resource id."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"can-i-parallelise-a-scan-by-splitting-the-cursor-across-workers","__idx":19},"children":["Can I parallelise a scan by splitting the cursor across workers?"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["No — give each worker a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["disjoint filter"]}," (e.g. a distinct time range) instead. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/guides/pagination#guidance"},"children":["Pagination"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"reporting-a-bug","__idx":20},"children":["Reporting a bug"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Include ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error.request_id"]}]}," from the failing response — without it we cannot correlate your call to server logs. Full checklist in ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/guides/errors#reporting-a-bug"},"children":["Errors → Reporting a bug"]},"."]}]},"headings":[{"value":"FAQ & Troubleshooting","id":"faq--troubleshooting","depth":1},{"value":"Auth & login","id":"auth--login","depth":2},{"value":"How do I get a token?","id":"how-do-i-get-a-token","depth":3},{"value":"I'm getting 401 Unauthorized . Why?","id":"im-getting-401-unauthorized--why","depth":3},{"value":"I'm getting 403 Forbidden . Why?","id":"im-getting-403-forbidden--why","depth":3},{"value":"Rate limits","id":"rate-limits","depth":2},{"value":"I'm getting 429 Too Many Requests . What do I do?","id":"im-getting-429-too-many-requests--what-do-i-do","depth":3},{"value":"Do MCP and REST share a rate-limit budget?","id":"do-mcp-and-rest-share-a-rate-limit-budget","depth":3},{"value":"How do I get higher limits?","id":"how-do-i-get-higher-limits","depth":3},{"value":"Idempotency","id":"idempotency","depth":2},{"value":"I retried a flag action and got a conflict. What does that mean?","id":"i-retried-a-flag-action-and-got-a-conflict-what-does-that-mean","depth":3},{"value":"MCP connector setup","id":"mcp-connector-setup","depth":2},{"value":"I added the Titan MCP connector but the client doesn't call it.","id":"i-added-the-titan-mcp-connector-but-the-client-doesnt-call-it","depth":3},{"value":"The MCP endpoint returns 401 .","id":"the-mcp-endpoint-returns-401-","depth":3},{"value":"The MCP endpoint returns 403 .","id":"the-mcp-endpoint-returns-403-","depth":3},{"value":"The connector connects but returns no data.","id":"the-connector-connects-but-returns-no-data","depth":3},{"value":"Pagination","id":"pagination","depth":2},{"value":"How do I know I've reached the end?","id":"how-do-i-know-ive-reached-the-end","depth":3},{"value":"The cursor stopped working after a while.","id":"the-cursor-stopped-working-after-a-while","depth":3},{"value":"Can I parallelise a scan by splitting the cursor across workers?","id":"can-i-parallelise-a-scan-by-splitting-the-cursor-across-workers","depth":3},{"value":"Reporting a bug","id":"reporting-a-bug","depth":2}],"frontmatter":{"seo":{"title":"FAQ & Troubleshooting"}},"lastModified":"2026-08-19T12:45:50.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/docs/guides/faq","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}