{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Authentication Setup","description":"Developer documentation for integrating systems that send messages, plus reporting and operational APIs for platform holders."},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"authentication-setup","__idx":0},"children":["Authentication Setup"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["All API access to the Digital Post Platform is authenticated using certificate-based machine-to-machine authentication and OAuth 2.0."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Before sending messages or accessing platform APIs, a system integration must be created and configured, and a valid access token must be obtained."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This section explains how to configure authentication and obtain credentials for API access."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"overview","__idx":1},"children":["Overview"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Authentication is based on:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Client certificate authentication"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["JSON Web Tokens (JWT)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["OAuth 2.0 token exchange"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each integrating system authenticates using a registered system integration and a client certificate."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The general process is:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Generate the private key"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Generate the public certificate"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Create a System Integration"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Generate JWTs using the private key"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Exchange JWTs for access tokens"]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"create-the-private-key-file-private-keypem","__idx":2},"children":["Create the private key file (private-key.pem)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Authentication is based on X.509 client certificates. For each system integration, the integrator must hold a private key that matches the registered public certificate. This private key is used locally by the integrating system to sign JWTs and must never be shared."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Generate a 2048-bit RSA private key in PEM format using OpenSSL:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"<code >openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out private-key.pem</code>\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Result"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["private-key.pem — your private RSA key in PEM format."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Important notes"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Store private-key.pem securely (preferably in a secret manager or HSM where available)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Limit file access (e.g., strict permissions) and ensure it is not committed to source control."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The private key must remain with the integrating system and must never be uploaded or distributed."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"generate-the-public-certificate-file-publickeycer","__idx":3},"children":["Generate the public certificate file (publickey.cer)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each system integration must have one registered public certificate with a corresponding private key held by the integrator. The public certificate is uploaded in the Administration Portal so the platform can verify the JWT signatures created using your private key."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Generate a self-signed X.509 certificate (public certificate) in PEM format from your private key. Keep the validity at 365 days:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"openssl req -new -x509 -key private-key.pem -out publickey.cer -days 365\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Result"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["publickey.cer — your public X.509 certificate in PEM format (contains the public key)."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Important notes"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Upload publickey.cer to the Administration Portal when creating/configuring the system integration."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The certificate is used to verify the JWT signatures (the JWTs are signed with the private key; verification happens using the uploaded public certificate)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Plan certificate rotation before expiry (365 days) to avoid authentication interruptions."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"create-a-system-integration","__idx":4},"children":["Create a System Integration"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A system integration represents the technical client that authenticates against the platform."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["System integrations are created in the Administration Portal."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To create a system integration:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Select an organisation"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Navigate to Distribution → System integration"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Click Add System integration"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Enter a name"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Upload a certificate"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Enter contact information"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Select permissions:",{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Send message"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Retrieve billing data (if required)"]}]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Set status to Active"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Click Save"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Only active system integrations can authenticate."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each system integration is assigned a unique:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["machineId"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This identifier is required for authentication."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"collect-required-identifiers","__idx":5},"children":["Collect Required Identifiers"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Before implementing authentication, the following identifiers must be collected from the Administration Portal."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"machine-identifier","__idx":6},"children":["Machine Identifier"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["machineId",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},"Identifies the system integration."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"certificate-thumbprint","__idx":7},"children":["Certificate Thumbprint"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Certificate thumbprint",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},"Used as the issuer value in JWTs."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["These identifiers are required when creating JWTs and submitting API requests."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"machine-authentication","__idx":8},"children":["Machine Authentication"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"create-a-json-web-token","__idx":9},"children":["Create a JSON Web Token"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Authentication requires creating a signed JWT in accordance with RFC 7519."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The JWT must be signed using RS256 and the private key registered with the system integration."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"required-claims","__idx":10},"children":["Required Claims"]},{"$$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":{"align":"left","data-label":"Claim"},"children":["Claim"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Full name"},"children":["Full name"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["jti"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["JWT id"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Unique id for token e.g. GUID."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["iss"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Issuer"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Thumbprint of client certificate used for signing the JWT."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["sub"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Subject"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Id of the System integration to request a token for (Machine id)."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["aud"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Audience"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["URL of the Security Token Service requesting the token from, e.g. admin-test.digitalpost.dk."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["exp"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Expiration time"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["NumericDate (Epoch) specifying the time from which the token is valid. It must not be more than 5 minutes before Issued At."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["nbf"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Not before"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["NumericDate (Epoch) specifying the time from which the token is valid. It must not be more than 5 minutes before Issued At."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["iat"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Issued at"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["NumericDate (Epoch) specifying the time the token was issued."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"example-payload","__idx":11},"children":["Example Payload"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"jti\": \"56aec5e8-5895-45eb-8a2b-6afb65d9bf4s\",\n  \"iss\": \"38d00f87072131f1444d779ca6c75219b102de50\",\n  \"sub\": \"38\",\n  \"aud\": \"admin.digitalpostbox.xxx\",\n  \"iat\": 1572382814,\n  \"exp\": 1572382899,\n  \"nbf\": 1572382814\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The token lifetime must not exceed five minutes."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"example-jwt-creation-flow","__idx":12},"children":["Example JWT Creation Flow"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Pseudocode example:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"text","header":{"controls":{"copy":{}}},"source":"now = getCurrentTime()\nplatformDomain = getPlatformDomain()\n\nheader = {\n  alg: \"RS256\",\n  typ: \"JWT\"\n}\n\npayload = {\n  jti: generateUuid(),\n  iss: getCertificateThumbprint(),\n  sub: getMachineId(),\n  aud: platformDomain,\n  exp: now + 300,\n  nbf: now,\n  iat: now\n}\n\nencodedHeader = base64Url(header)\nencodedPayload = base64Url(payload)\n\nsigningInput = encodedHeader + \".\" + encodedPayload\n\nsignature = sign(signingInput, privateKey)\n\ntoken = signingInput + \".\" + signature\n","lang":"text"},"children":[]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"exchange-jwt-for-access-token","__idx":13},"children":["Exchange JWT for Access Token"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Once a JWT has been created, it must be exchanged for an access token."," ","To obtain an access token, the signed JWT must be sent to the platform Login Service token endpoint."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The JWT is submitted as a UTF-8 and Base64 encoded form parameter named ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["token"]},".",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},"The OAuth grant type ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["clientcertificate"]}," and client id ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["clientcertificate"]}," must be used.",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},"No client secret is required."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If authentication is successful, the Security Token Service issues an access token valid for approximately ten minutes.",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},"This token must be included as a Bearer token in the Authorization header when calling platform APIs."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"token-endpoint","__idx":14},"children":["Token Endpoint"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"text","header":{"controls":{"copy":{}}},"source":"POST https://<platform-domain>/loginservice/connect/token\n","lang":"text"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"request-format","__idx":15},"children":["Request Format"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Content Type: application x www form urlencoded"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"text","header":{"controls":{"copy":{}}},"source":"grant_type=clientcertificate\n&client_id=clientcertificate\n&token=<base64-encoded-jwt>\n","lang":"text"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["No client secret is required."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"example-request","__idx":16},"children":["Example Request"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"POST /loginservice/connect/token\nContent-Type: application/x-www-form-urlencoded\n\ngrant_type=clientcertificate&client_id=clientcertificate&token=eyJhbGciOi...\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"use-access-token-in-api-requests","__idx":17},"children":["Use Access Token in API Requests"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The token endpoint returns an access token."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This token must be included in all API requests:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"Authorization: Bearer <access-token>\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["All protected APIs require a valid bearer token."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"token-lifetime-and-renewal","__idx":18},"children":["Token Lifetime and Renewal"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Access tokens are valid for approximately ten minutes."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["After expiration:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A new JWT must be generated"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A new token must be requested"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Integrations should implement automatic token renewal."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Tokens must not be reused after expiration."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"user-authentication","__idx":19},"children":["User Authentication"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Some APIs may require user based authentication using OAuth 2.0 Authorization Code Grant with PKCE."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This flow is used for interactive user access and is separate from machine authentication."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Most system integrations only require machine authentication."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"practical-example-manual-certificate-and-token-setup","__idx":20},"children":["Practical Example: Manual Certificate and Token Setup"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This section provides a practical example of generating certificates, signing JWTs, and obtaining access tokens using commonly available tools."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["It supplements the general authentication flow described above and is intended for development and testing purposes."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"generate-certificate-using-openssl","__idx":21},"children":["Generate Certificate Using OpenSSL"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"openssl genpkey -algorithm RSA \\\n  -pkeyopt rsa_keygen_bits:2048 \\\n  -out private-key.pem\n\nopenssl req -new -x509 \\\n  -key private-key.pem \\\n  -out publickey.cer \\\n  -days 1825\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Upload publickey.cer when creating the system integration."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Store private-key.pem securely."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"create-and-validate-jwt-using-jwtio-optional","__idx":22},"children":["Create and Validate JWT Using jwt.io (Optional)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Tools such as jwt.io can be used for testing and validation during development only; they must not be used to generate JWTs in production, and private key material (e.g., a PEM file) must never be uploaded to third-party online services."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Select:"," ","•\tAlgorithm: RS256"," ","•\tHeader: Default"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Example payload:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"jti\": \"b639b8d9-d302-4cc5-8b83-aac451854492\",\n  \"iss\": \"BF6FAFD79CDFA2FBC9CCB685E78C5D9DBCF713B9\",\n  \"sub\": \"1733\",\n  \"aud\": \"http://securitytokenservice\",\n  \"exp\": 1568991626,\n  \"nbf\": 1568991086,\n  \"iat\": 1568991326\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Paste the public certificate and private key to validate the signature."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"obtain-access-token-using-curl","__idx":23},"children":["Obtain Access Token Using curl"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Example request:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X POST \\\n  https://<platform-domain>/loginservice/connect/token \\\n  -H \"Content-Type: application/x-www-form-urlencoded\" \\\n  -d \"grant_type=clientcertificate&client_id=clientcertificate&token=<jwt-token>\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The response contains the access token."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"troubleshooting-authentication","__idx":24},"children":["Troubleshooting Authentication"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Common authentication issues include:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Invalid certificate"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Incorrect thumbprint"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Expired JWT"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Invalid audience value"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Incorrect machineId"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Unsynchronized system clocks"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If authentication fails:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Verify certificate registration"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Verify JWT claims"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Check token endpoint URL"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Confirm system time accuracy"]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"next-steps","__idx":25},"children":["Next Steps"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["After authentication is configured, continue with:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/getting-started/prepare-message"},"children":["Prepare Your First Message"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/getting-started/choosesubmissionmethod"},"children":["Choose a Submission Method"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/getting-started/upload-s3"},"children":["Upload Content to S3"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/getting-started/submit-multipart"},"children":["Send Messages via Multipart"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/getting-started/verify-delivery"},"children":["Verify and Troubleshoot"]}]}]}]},"headings":[{"value":"Authentication Setup","id":"authentication-setup","depth":1},{"value":"Overview","id":"overview","depth":2},{"value":"Create the private key file (private-key.pem)","id":"create-the-private-key-file-private-keypem","depth":2},{"value":"Generate the public certificate file (publickey.cer)","id":"generate-the-public-certificate-file-publickeycer","depth":2},{"value":"Create a System Integration","id":"create-a-system-integration","depth":2},{"value":"Collect Required Identifiers","id":"collect-required-identifiers","depth":2},{"value":"Machine Identifier","id":"machine-identifier","depth":3},{"value":"Certificate Thumbprint","id":"certificate-thumbprint","depth":3},{"value":"Machine Authentication","id":"machine-authentication","depth":2},{"value":"Create a JSON Web Token","id":"create-a-json-web-token","depth":3},{"value":"Required Claims","id":"required-claims","depth":4},{"value":"Example Payload","id":"example-payload","depth":4},{"value":"Example JWT Creation Flow","id":"example-jwt-creation-flow","depth":3},{"value":"Exchange JWT for Access Token","id":"exchange-jwt-for-access-token","depth":3},{"value":"Token Endpoint","id":"token-endpoint","depth":4},{"value":"Request Format","id":"request-format","depth":4},{"value":"Example Request","id":"example-request","depth":4},{"value":"Use Access Token in API Requests","id":"use-access-token-in-api-requests","depth":3},{"value":"Token Lifetime and Renewal","id":"token-lifetime-and-renewal","depth":3},{"value":"User Authentication","id":"user-authentication","depth":2},{"value":"Practical Example: Manual Certificate and Token Setup","id":"practical-example-manual-certificate-and-token-setup","depth":2},{"value":"Generate Certificate Using OpenSSL","id":"generate-certificate-using-openssl","depth":3},{"value":"Create and Validate JWT Using jwt.io (Optional)","id":"create-and-validate-jwt-using-jwtio-optional","depth":3},{"value":"Obtain Access Token Using curl","id":"obtain-access-token-using-curl","depth":3},{"value":"Troubleshooting Authentication","id":"troubleshooting-authentication","depth":2},{"value":"Next Steps","id":"next-steps","depth":2}],"frontmatter":{"title":"Authentication Setup","description":"Configure certificate-based authentication and obtain access tokens for the Digital Post Platform APIs.","seo":{"title":"Authentication Setup"}},"lastModified":"2026-06-03T14:29:04.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/getting-started/authentication","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}