Skip to main content
Data Access includes a customer authorization dashboard which enables customers to manage the apps and intermediaries they have chosen to permission. This dashboard is designed to be embedded within your customer-facing web or mobile experience and is accessible at https://access.your-domain.com/embed/authorizations. Access is authenticated with either:
  • An access token
  • (Deprecated) Nested JSON Web Tokens (JWTs), which are signed and encrypted
These options let you authenticate customers and display the dashboard without cookies.

​
Access Token

PREREQUISITETo get your credentials in the Data Provider Portal, go to Configuration > Consent Dashboard Management and select Generate API credentials.
  1. Request a one-time access token from the Request Token endpoint. Include client_id and client_secret in the request header. The request body must include the consent_management scope and the customerId (must match openid_connect_user_id).
    • Every token is single-use and expires in five minutes
    • Request a new token after use or expiration
  2. Set your iframe’s src to the access_token you retrieved in the last step.
The widget is 512px wide and has a minimum height of 600px. If the iframe is wider, the widget centers; if taller, it can grow to the iframe height. The widget uses scrollbars if the content is longer than the height.

​
(Deprecated) JWTs

WARNINGFor new implementations, use an access token.
The following steps provide details on embedding the dashboard using JWTs. A workflow that describes consent management
  1. Generate an encrypted admin JWT on your own systems using your shared secret and the customer’s unique identifier.
  2. Use the admin JWT (step one) to request an encrypted, expiring, one-time use customer JWT from Data Access.
  3. Use the customer JWT (step two) as a query parameter to load the dashboard into an iframe.
INFOEvery customer JWT generated by Data Access is single-use and expires after 15 minutes.

​
Create an Admin JWT

First, create an admin JWT using JSON Web Encryption (JWE). Use an appropriate encryption library to generate an admin JWT with your shared secret and the unique identifier for the customer. An example shared secret might be Jx2qSDdJy6BJfkjH7PPZ6OPnjbjd/qNI2vgbCRT30Qw=. MX strongly recommends using a Javascript Object Signing and Encryption (JOSE) library to handle JWE creation. There are many libraries and implementations available for different languages. Javascript and Ruby examples are shown here. Data Access uses AES256-GCM. The encrypted object must contain the sub claim, for example {"sub": "sub-id-1234"}. This is the same as the subject identifier outlined in the OIDC spec. It’s the unique identifier for that user in your system.
INFOKeep your shared secret safe. When an admin request body is correctly decrypted in Data Access, it is considered to be from a trusted source.
const crypto = require('crypto');
const { CompactEncrypt } = require('jose/jwe/compact/encrypt');
const { compactDecrypt } = require('jose/jwe/compact/decrypt');
class SecureMessageService {
  constructor(key) {
    this.encoder = new TextEncoder();
    this.decoder = new TextDecoder();
    this.key = crypto.createSecretKey(Buffer.from(key, 'base64'));
}
  async encrypt(obj) {
    return await new CompactEncrypt(this.encoder.encode(JSON.stringify(obj)))
      .setProtectedHeader({ alg: 'dir', enc: 'A256GCM' })
      .encrypt(this.key);
  }
  async decrypt(encrypted) {
    const { plaintext } = await compactDecrypt(encrypted, this.key);
    return this.decoder.decode(plaintext);
} }
module.exports = SecureMessageService;

require "jose"

class JWE
 def self.encrypt(obj)
   ::JOSE::JWE.block_encrypt(key, obj.to_json, "alg" => "dir", "enc" => "A256GCM").compact
 end

 def self.decrypt(encrypted)
   ::JSON.parse(::JOSE::JWE.block_decrypt(key, encrypted).first)
 end

 def self.key
::JOSE::JWK.from_oct(Base64.decode64(SHARED_SECRET))
 end

end

​
Create a Customer JWT

Next, use this endpoint to create a JWT for the specified customer based on their unique subject identifier included in the previous section. If a customer with the given sub hasn’t yet been created in Data Access, using this endpoint will create it. Endpoint: POST /admin/customers/jwt 
curl -L -X POST 'https://access.your-domain.com/admin/customers/jwt' \
-H 'Content-Type: text/plain' \
-d 'eyJlbmMiOiJBMjU2R0NNIiwiYWxnIjoiZ ... FEaFMXMQ4H9znE3yrJsMDy7WnCeJEg'

{end-user jwt}

​
Embed the Dashboard

To embed the customer consent-management widget in an iframe, pass the jwt query parameter into the route with the customer JWT as the value. This will authorize the view for the specified customer without reauthentication. Endpoint: GET /embed/authorizations?jwt=${customer_jwt} The widget is 512px wide and has a minimum height of 600px. If the iframe is wider, the widget centers; if taller, it can grow to the iframe height. The widget uses scrollbars if the content is longer than the height.
WARNINGEvery JWT generated by Data Access is single-use. Once this token has been used to load the dashboard, a page refresh with the same token will result in a 404 Unauthorized status.