{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Authentication Guide","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"authentication-guide","__idx":0},"children":["Authentication Guide"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"two-sets-of-credentials","__idx":1},"children":["Two Sets of Credentials"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Remember, Congruit maintains two environments:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Sandbox"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Production"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Your Organization/company ID, Portfolio IDs, and Explans are synced across ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["both"]}," environments."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["However, your credentials ",{"$$mdtype":"Tag","name":"u","attributes":{},"children":["remain separate"]},". Sandbox credentials will not work in Production, and vice versa."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Your workhorse API calls (calling endpoints like ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["evaluation"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ach_transactions"]},") require a short-lived (24 hours) bearer token in the request header. Bearer tokens are fetched from the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tokens"]}," endpoint using your ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ClientID"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ClientSecret"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["We will supply your Sandbox credentials at the begining of the onboarding process, and your Production credentials after approval of your onboarding success."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"oauth-flow","__idx":2},"children":["OAuth Flow"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Congruit uses ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://oauth.net/2/"},"children":["OAuth 2.0"]}," workflow for access/authentication management using bearer tokens (refresh tokens are not used)."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Call our ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tokens"]}," endpoint to fetch a bearer token. That bearer token can then be used to authenticate your call to our workhorse API endpoints such as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["evaluation"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Bearer tokens are only valid for a period of time; after that time you need to call for a new bearer token."]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Fetch Bearer Token"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl --request POST https://api.congruitcredit.com/tokens \\\n     --header \"Content-Type: application/json\" \\\n     --data '{\"token\": \\\n     {\"client_id\":\"Tl0MJLZviPysiz6saxx7TKivMCoVJcDZ\", \\\n     \"client_secret\":\"uTWAMB7M4kxxuvVcBlL__ynXGSoTCHkbZelLRNG6vy1bMJxXxzOSQCrxUB8_G3e7\"} \\\n     }'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\"token\":\"eyJhbGciOiJSUzI1NixxInR5cCI6IkpXVCIsImtpZCI6IkJ4Wnl3MUZyWF84LUxLMWlLTFJ0aCJ9.eyJodHRwczovL2Rldi12YW5nL2FwaS92MS9vcmdhbml6YXRpb25faWQiOiJPUkcjMDE5OGEzZGUtOWMxNS03ZjlkLTkwMDktNzhmOGNkMTlhYzhlIiwiaXNzIjoiaHR0cHM6Ly9kZXZlbG9wbWVudC1jb25ncnVpdGNyZWRpdC51cy5hdXRoMC5jb20vIiwic3ViIjoidE92RmJNWVp1enZBMWhzQkI4bm1BNm4xb0ZXcm9PNmtAY2xpZW50cyIsImF1ZCI6Imh0dHBzOi8vZGV2LXZhbmcvYXBpL3YxLyIsImlhdCI6MTc1NTEwNzI3OCwiZXhwIjoxNzU1MTkzNjc4LCJndHkiOiJ1bGllbnQtY3JlZGVudGlhbHMiLCJhenAiOiJ0T3ZGYk1ZWnV6dkExaHNCQjhubUE2bjFvRldyb082ayJ9.Z4CqoXZAE52c2jRiRGnSazl8s-D84cU1ltSl_WZlmKF8BrqtdXQNzoMKK-xH2XNKhxojGSEFzBGaJ9gEdjyrQ-Pzum0jzmrs7Nnppr5f32gXWREHe28fH7pHlNV22dQVaTIrDSWAu-dNPCTr1heHnaDNNHFB0TBJzNMYULxiHw7ygu0eMsnd5_QHeU6bQNwfSoQ1N-4gJQe6IctfZ_UR_WBG27fMtiNbxNF8_Su6Hvb7cFml8uSUBH1HJqRLShyPhqXP18LJqOKEdHbF3FQQIofPe-F6gy29eo07fI69VYcNM6k0Pg5m9wGSEEAtKRndI0a89CKJjuPjiWRlDCJFvg\",\n  \"expires_at\":1755100800,\n  \"token_type\":\"Bearer\"}\n","lang":"json"},"children":[]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Use Bearer Token"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl --header \"Authorization: Bearer BEARER_TOKEN\" \\\n     https://api.congruitcredit.com/v1/[endpoint] \\\n     --data {payload}\n\n","lang":"bash"},"children":[]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Refresh Bearer Token"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each bearer token expires in 24 hours, so your application should:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["cache the bearer token locally so that you avoid the overhead latency of the token call for your workhorse API calls."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["set your cache entry to expire at the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["expires_at"]}," epoch time in the fetch response."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["as your cache expires, fetch a new bearer token to cache locally and use."]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Note that this process does not use a refresh token like some other refresh patterns."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Do you absolutely need to cache the bearer token? No, you could request it prior to every API call but that adds latency. No matter how many times you call Congruit for a bearer token, you will receive the ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["same"]}," token in response until the token expires."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"security-best-practices","__idx":3},"children":["Security Best Practices"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"api-token-security","__idx":4},"children":["API Token Security"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Store securely"]},": Never hardcode tokens or secrets in your application."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Environment variables"]},": Use environment variables for secrets."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Monitor usage"]},": Watch for unusual activity."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"permitted-ips","__idx":5},"children":["Permitted IPs"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For enhanced security, you must add your development, test, staging, and production IP addresses to our allowlist. Please supply these to us during onboarding."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"tls-version","__idx":6},"children":["TLS Version"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["We require TLS 1.3 for all API connections. Only these ciphers are supported (AWS Best Practice):"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["TLS_AES_128_GCM_SHA256"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["TLS_AES_256_GCM_SHA384"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["TLS_CHACHA20_POLY1305_SHA256"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"error-handling","__idx":7},"children":["Error Handling"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"authentication-errors","__idx":8},"children":["Authentication Errors"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Error Code"},"children":["Error Code"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Solution"},"children":["Solution"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Invalid client credentials"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Check your Client ID and Client Secret with your Congruit Account Manager"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["429"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Rate limit exceeded"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Wait and retry"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"example-error-response","__idx":9},"children":["Example Error Response"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\"error\": \"unauthorized\"}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"testing-authentication","__idx":10},"children":["Testing Authentication"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"health-check","__idx":11},"children":["Health Check"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Check that the system is up and responding:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl  --request POST https://api.congruitcredit.com/tokens/health_check\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"{\"I'm alive at 2025-06-04 23:15:04 CHECK THIS\"}\n"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"token-validation","__idx":12},"children":["Token Validation"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Validate an OAuth token is working (unexpired):"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -H \"Authorization: Bearer ACCESS_TOKEN\" \\\n     https://api.yourcompany.com/tokens/validate\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"valid\": true,\n  \"message\": \"The token is valid.\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If the bearer token has expired, then you will receive a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401"]}," HTTP error. Simply request a new bearer token."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"getting-help","__idx":13},"children":["Getting Help"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Support"]},": Email ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"mailto:support@congruitcredit.com"},"children":["support@congruitcredit.com"]}]}]},"headings":[{"value":"Authentication Guide","id":"authentication-guide","depth":1},{"value":"Two Sets of Credentials","id":"two-sets-of-credentials","depth":3},{"value":"OAuth Flow","id":"oauth-flow","depth":4},{"value":"Security Best Practices","id":"security-best-practices","depth":2},{"value":"API Token Security","id":"api-token-security","depth":3},{"value":"Permitted IPs","id":"permitted-ips","depth":3},{"value":"TLS Version","id":"tls-version","depth":3},{"value":"Error Handling","id":"error-handling","depth":2},{"value":"Authentication Errors","id":"authentication-errors","depth":3},{"value":"Example Error Response","id":"example-error-response","depth":3},{"value":"Testing Authentication","id":"testing-authentication","depth":2},{"value":"Health Check","id":"health-check","depth":3},{"value":"Token Validation","id":"token-validation","depth":3},{"value":"Getting Help","id":"getting-help","depth":3}],"frontmatter":{"seo":{"title":"Authentication Guide"}},"lastModified":"2026-03-10T15:36:38.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/guides/authentication","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}