{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Getting Started"},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"getting-started","__idx":0},"children":["Getting Started"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The Titan Public API gives external developers programmatic access to SecurityScorecard observations and related resources. This guide walks a new caller from zero to a first successful response."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"prerequisites","__idx":1},"children":["Prerequisites"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["An admin role in your SecurityScorecard organization (required to issue credentials)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A current API major to target (see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/guides/versioning"},"children":["Versioning & lifecycle"]}," for how to pick one)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A shell with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["curl"]}," (or any HTTP client)."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-1--obtain-client-credentials","__idx":2},"children":["Step 1 — Obtain client credentials"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Credentials are issued from ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Credential Management"]}," in the SecurityScorecard UI. The Titan Public API uses ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["OAuth 2.0 client credentials"]}," — each calling system holds a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CLIENT_ID"]}," / ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CLIENT_SECRET"]}," pair, exchanges it for a short-lived access token, and attaches that token as a bearer credential on every API request."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"open-credential-management","__idx":3},"children":["Open Credential Management"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In the SecurityScorecard app, navigate to ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Connectors → APIs"]}," in the left sidebar, then click ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["+ Create credential"]}," in the top right."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"img","attributes":{"src":"/assets/1-api-credentials-list.32731c42961d127f401e9ae3657fe1ae086d64210d4fc2e3fc2622c8cbeb3503.97313a7d.png","alt":"API Credentials list with Connectors → APIs highlighted in the sidebar and the Create credential button highlighted in the top right"},"children":[]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"configure-the-new-credential","__idx":4},"children":["Configure the new credential"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A slide-out panel opens. Provide:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Label"]}," — a human-readable name for this credential (up to 80 characters). Use something that identifies the calling system, e.g. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["nightly-etl-job"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["contract-tests"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Scopes"]}," — pick the permissions this credential should carry. Available scopes today:",{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Read security findings"]}," — read-only access across REST and MCP endpoints."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Flag security findings"]}," — dispatch flag actions on observations."]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Grant only the scopes the caller actually needs."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"img","attributes":{"src":"/assets/2-create-credential-form.678dbfe5eff5ba161c6d1c3adf14116ce3b80d4973db90b607d83bea9814329c.97313a7d.png","alt":"Create credential form with Label, Scopes checkboxes, and a warning that the client secret is shown only once"},"children":[]}]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Note:"]}," The client secret is revealed ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["once"]},", immediately after you click ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Generate credential"]},". Once you dismiss the dialog, the secret cannot be retrieved again — you'd have to create a new credential and delete the old one. Have your secret store ready before you click Generate."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"save-the-client-secret","__idx":5},"children":["Save the client secret"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["After clicking Generate, the dialog shows the newly-issued ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Client ID"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Client secret"]},". Copy both immediately into your secret manager, or download the pre-formatted ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".env"]}," file with the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Download .env"]}," button."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"img","attributes":{"src":"/assets/3-credential-created.f1169192180df9232c79ab2f58a35a155391b78d731763675b19df81e34fc3aa.97313a7d.png","alt":"Credential created dialog showing the Client ID, masked Client secret, a Download .env button, and REST/MCP usage examples"},"children":[]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-2--exchange-credentials-for-an-access-token","__idx":6},"children":["Step 2 — Exchange credentials for an access token"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["With the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CLIENT_ID"]}," / ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CLIENT_SECRET"]}," in hand, exchange them for an access token:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"TITAN_API_TOKEN=$(curl -sX POST 'https://titanapi.securityscorecard.io/v1/oauth/token' \\\n  -u \"$CLIENT_ID:$CLIENT_SECRET\" \\\n  -d 'grant_type=client_credentials' | jq -r .access_token)\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The response includes a bearer token and its lifetime. Cache the token until it expires — do not exchange credentials on every request."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-3--make-your-first-request","__idx":7},"children":["Step 3 — Make your first request"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["With the access token in hand, call any public endpoint. Endpoints live under the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/public/<major>/"]}," path prefix:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl https://titanapi.securityscorecard.io/public/v1/observations \\\n  -H \"Authorization: Bearer $TITAN_API_TOKEN\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A successful call returns a JSON payload with the resource data."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"using-the-same-credentials-with-mcp","__idx":8},"children":["Using the same credentials with MCP"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The client credentials you just created work for ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["both REST and MCP"]}," — the Titan MCP server accepts the same OAuth bearer token. See the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/guides/mcp"},"children":["MCP guide"]}," for the endpoint URL, client configuration, and a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tools/list"]}," example."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"rotating-credentials","__idx":9},"children":["Rotating credentials"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Credentials should be rotated periodically. To rotate:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Create a new credential pair with the same scopes as the old one."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Roll the new pair out to callers."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Once every caller has switched over, delete the old credential from the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Connectors → APIs"]}," page."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"next-steps","__idx":10},"children":["Next steps"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Browse the full endpoint catalog in the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["API Reference"]}," (sidebar)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Learn how ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/guides/versioning"},"children":["versioning and lifecycle signals"]}," are surfaced on every operation."]}]}]},"headings":[{"value":"Getting Started","id":"getting-started","depth":1},{"value":"Prerequisites","id":"prerequisites","depth":2},{"value":"Step 1 — Obtain client credentials","id":"step-1--obtain-client-credentials","depth":2},{"value":"Open Credential Management","id":"open-credential-management","depth":3},{"value":"Configure the new credential","id":"configure-the-new-credential","depth":3},{"value":"Save the client secret","id":"save-the-client-secret","depth":3},{"value":"Step 2 — Exchange credentials for an access token","id":"step-2--exchange-credentials-for-an-access-token","depth":2},{"value":"Step 3 — Make your first request","id":"step-3--make-your-first-request","depth":2},{"value":"Using the same credentials with MCP","id":"using-the-same-credentials-with-mcp","depth":2},{"value":"Rotating credentials","id":"rotating-credentials","depth":2},{"value":"Next steps","id":"next-steps","depth":2}],"frontmatter":{"seo":{"title":"Getting Started"}},"lastModified":"2026-08-19T12:45:50.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/docs/guides/getting-started","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}