1/*! For license information please see 03dbbd46.97da824d.js.LICENSE.txt */ 2"use strict";(self.webpackChunkdevelopers_basistheory_com=self.webpackChunkdevelopers_basistheory_com||[]).push([[1442],{89163:(e,n,t)=>{t.d(n,{Ay:()=>l,RM:()=>s});var a=t(74848),r=t(28453),i=t(85202);const s=[];function o(e){return(0,a.jsx)(i.F,{type:i.W.WARNING,children:"The response from this service is the actual plaintext data. It may contain sensitive data depending on the third-party API response."})}function l(e={}){const{wrapper:n}={...(0,r.R)(),...e.components};return n?(0,a.jsx)(n,{...e,children:(0,a.jsx)(o,{...e})}):o()}},15174:(e,n,t)=>{t.d(n,{Ay:()=>d,RM:()=>o});var a=t(74848),r=t(28453),i=t(85202),s=t(78581);const o=[];function l(e){const n={a:"a",p:"p",...(0,r.R)(),...e.components};return(0,a.jsxs)(a.Fragment,{children:[(0,a.jsx)(n.p,{children:"Our Elements enable you to convert proxy responses into plain text, which is ideal for non-sensitive data handling. This enhancement streamlines your data processing workflows and facilitates an easier understanding of the returned data, bypassing decryption or tokenization."}),"\n",(0,a.jsxs)(n.p,{children:["This feature is currently invite-only. If you're interested, please ",(0,a.jsx)(s.A,{to:"https://basistheory.com/contact",target:"_blank<",children:"get in touch"})," for an invitation."]}),"\n",(0,a.jsxs)(i.F,{type:i.W.WARNING,children:["You can capture values from any of our Elements; hence we strongly recommend only using this feature for non-sensitive data. Converting proxy responses to plain text can expose the underlying data to risks, such as unauthorized access or leakage. Ensure the plain-text proxy responses align with your data security policy, data handling practices, and compliance obligations. If you're unsure, please get in touch for guidance at ",(0,a.jsx)(s.A,{href:"https://www.basistheory.com/contact",target:"_blank",children:(0,a.jsx)(n.a,{href:"http://www.basistheory.com/contact",children:"www.basistheory.com/contact"})})]})]})}function d(e={}){const{wrapper:n}={...(0,r.R)(),...e.components};return n?(0,a.jsx)(n,{...e,children:(0,a.jsx)(l,{...e})}):l(e)}},66755:(e,n,t)=>{t.r(n),t.d(n,{assets:()=>p,contentTitle:()=>c,default:()=>m,frontMatter:()=>d,metadata:()=>a,toc:()=>h});const a=JSON.parse('{"id":"sdks/web/web-elements/services","title":"Web Elements Services","description":"Basis Theory Web Elements offers a set of services that enable you to securely collect, manage, encrypt, and share sensitive data without exposing it to your application code. This document explains the available services and how to use them in your applications.","source":"@site/docs/sdks/web/web-elements/services.mdx","sourceDirName":"sdks/web/web-elements","slug":"/sdks/web/web-elements/services","permalink":"/docs/sdks/web/web-elements/services","draft":false,"unlisted":false,"tags":[],"version":"current","lastUpdatedAt":1790020069000,"frontMatter":{"title":"Web Elements Services","sidebar_label":"Services"},"sidebar":"sdk","previous":{"title":"Lifecycle","permalink":"/docs/sdks/web/web-elements/lifecycle"},"next":{"title":"Migrating to Web Elements","permalink":"/docs/sdks/web/web-elements/migration"}}');var r=t(74848),i=t(28453),s=t(85202),o=t(15174),l=t(89163);const d={title:"Web Elements Services",sidebar_label:"Services"},c="Web Elements Services",p={},h=[{value:"Overview",id:"overview",level:2},{value:"Element Methods",id:"element-methods",level:2},{value:"Data Collection",id:"data-collection",level:2},{value:"Tokenizing Data",id:"tokenizing-data",level:3},{value:"1. Create a Single Token",id:"1-create-a-single-token",level:4},{value:"Create a Card Token",id:"create-a-card-token",level:4},{value:"Create a Bank Account Token",id:"create-a-bank-account-token",level:4},{value:"2. Tokenize Multiple Values at Once",id:"2-tokenize-multiple-values-at-once",level:4},{value:"Updating Tokens",id:"updating-tokens",level:3},{value:"Creating Token Intents",id:"creating-token-intents",level:3},{value:"Data Encryption",id:"data-encryption",level:2},{value:"Encrypting Data",id:"encrypting-data",level:3},{value:"1. Encrypt a Single Token Payload",id:"1-encrypt-a-single-token-payload",level:4},{value:"Encrypt a Card Token Payload",id:"encrypt-a-card-token-payload",level:4},{value:"2. Encrypt Multiple Token Payloads at Once",id:"2-encrypt-multiple-token-payloads-at-once",level:4},{value:"Data Retrieval",id:"data-retrieval",level:2},{value:"Retrieving and Displaying Tokenized Data",id:"retrieving-and-displaying-tokenized-data",level:3},{value:"Displaying Card Data",id:"displaying-card-data",level:3},{value:"Session Management",id:"session-management",level:2},{value:"Creating Sessions",id:"creating-sessions",level:3},{value:"Third-Party Integration",id:"third-party-integration",level:2},{value:"Proxy Service",id:"proxy-service",level:3},{value:"Supported HTTP Methods",id:"supported-http-methods",level:4},{value:"Proxy Request Options",id:"proxy-request-options",level:4},{value:"Accessing Non-Sensitive Proxy Responses",id:"accessing-non-sensitive-proxy-responses",level:4},...o.RM,{value:"HTTP Client Service",id:"http-client-service",level:3},...l.RM,{value:"Supported HTTP Methods",id:"supported-http-methods-1",level:4},{value:"Error Handling",id:"error-handling",level:2},{value:"Basis Theory Service Errors",id:"basis-theory-service-errors",level:3},{value:"HTTP Client Service Errors",id:"http-client-service-errors",level:3},{value:"Error Types Reference",id:"error-types-reference",level:3},{value:"BasisTheoryValidationError",id:"basistheoryvalidationerror",level:4},{value:"BasisTheoryApiError",id:"basistheoryapierror",level:4},{value:"HttpClientError",id:"httpclienterror",level:4},...l.RM];function u(e){const n={a:"a",code:"code",h1:"h1",h2:"h2",h3:"h3",h4:"h4",header:"header",li:"li",p:"p",pre:"pre",strong:"strong",table:"table",tbody:"tbody",td:"td",th:"th",thead:"thead",tr:"tr",ul:"ul",...(0,i.R)(),...e.components};return(0,r.jsxs)(r.Fragment,{children:[(0,r.jsx)(n.header,{children:(0,r.jsx)(n.h1,{id:"web-elements-services",children:"Web Elements Services"})}),"\n",(0,r.jsx)(n.p,{children:"Basis Theory Web Elements offers a set of services that enable you to securely collect, manage, encrypt, and share sensitive data without exposing it to your application code. This document explains the available services and how to use them in your applications."}),"\n",(0,r.jsx)(n.h2,{id:"overview",children:"Overview"}),"\n",(0,r.jsx)(n.p,{children:"The services provided by Basis Theory Web Elements fall into four main categories:"}),"\n",(0,r.jsxs)(n.ul,{children:["\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.strong,{children:"Data Collection"})," - Securely collect, and tokenize sensitive data"]}),"\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.strong,{children:"Data Encryption"})," - Securely encrypt sensitive data using public key encryption"]}),"\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.strong,{children:"Data Retrieval"})," - Safely detokenize and reveal sensitive data"]}),"\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.strong,{children:"Session Management"})," - Create and manage temporary access sessions"]}),"\n",(0,r.jsxs)(n.li,{children:[(0,r.jsx)(n.strong,{children:"Third-Party Integration"})," - Securely interact with third-party APIs"]}),"\n"]}),"\n",(0,r.jsx)(s.F,{children:"Each service is designed to maintain a security boundary for sensitive data. The actual input data never leaves the element (iframe) other than to hit our secure API endpoints."}),"\n",(0,r.jsx)(n.h2,{id:"element-methods",children:"Element Methods"}),"\n",(0,r.jsx)(n.p,{children:"Elements provide several methods for interacting with and manipulating their values securely. These methods allow you to programmatically control elements while maintaining the security boundary."}),"\n",(0,r.jsxs)(n.p,{children:["For detailed documentation on all available methods, see the ",(0,r.jsx)(n.a,{href:"/docs/sdks/web/web-elements/methods",children:"Element Methods"})," reference."]}),"\n",(0,r.jsx)(n.h2,{id:"data-collection",children:"Data Collection"}),"\n",(0,r.jsx)(n.h3,{id:"tokenizing-data",children:"Tokenizing Data"}),"\n",(0,r.jsx)(n.p,{children:"Basis Theory Elements can securely tokenize sensitive data without exposing it to your application. You can tokenize data using two primary approaches:"}),"\n",(0,r.jsx)(n.h4,{id:"1-create-a-single-token",children:"1. Create a Single Token"}),"\n",(0,r.jsxs)(n.p,{children:["The ",(0,r.jsx)(n.code,{children:"tokens.create"})," method creates a single token with your sensitive data:"]}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-javascript",children:'// Create a token containing sensitive data\nbt.tokens\n .create({\n type: "token", // Specify the token type\n data: {\n // Include element instances containing sensitive data\n sensitiveData: sensitiveDataElement, // Data remains in secure iframe\n \n // Include non-sensitive data directly\n nonSensitiveData: "plainText", \n \n // Nested data structures are supported\n otherData: {\n someInteger: 20,\n someBoolean: false,\n },\n someOtherData: ["plainText1", "plainText2"],\n },\n // Optional metadata (non-sensitive)\n metadata: {\n nonSensitiveField: "nonSensitiveValue",\n },\n })\n .then((token) => {\n // Save the token ID for future reference\n console.log(token.id); \n \n // Full response includes masked/redacted data\n console.log(JSON.stringify(token)); \n });\n'})}),"\n",(0,r.jsxs)(s.F,{type:s.W.WARNING,children:["When submitting ",(0,r.jsx)("code",{children:"plainText"})," values, data will be HTML encoded before storage for security reasons."]}),"\n",(0,r.jsx)(n.h4,{id:"create-a-card-token",children:"Create a Card Token"}),"\n",(0,r.jsxs)(n.p,{children:["For payment card data, you can use either the combined ",(0,r.jsx)(n.code,{children:"CardElement"})," or individual card elements:"]}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-javascript",children:'// Option 1: Using the combined CardElement\nbt.tokens\n .create({\n type: "card", // Specific type for cards\n data: cardElement, // Pass the entire card element\n })\n .then((token) => {\n console.log(token.id);
2 // Token to store\n console.log(JSON.stringify(token.data)); // Contains masked card data\n });\n\n// Option 2: Using individual card elements\nbt.tokens\n .create({\n type: "card",\n data: {\n // Each piece of card data in a separate element\n number: cardNumberElement,\n expiration_month: cardExpirationDateElement.month(), // Using the data parsing method\n expiration_year: cardExpirationDateElement.year(),\n cvc: cardVerificationCodeElement\n }\n })\n .then((token) => {\n console.log(token.id);\n console.log(JSON.stringify(token.data)); // Masked card data\n });\n'})}),"\n",(0,r.jsx)(n.h4,{id:"create-a-bank-account-token",children:"Create a Bank Account Token"}),"\n",(0,r.jsx)(n.p,{children:"For bank account information:"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-javascript",children:'bt.tokens\n .create({\n type: "bank",\n data: {\n routingNumber: routingNumberElement,\n accountNumber: accountNumberElement,\n },\n })\n .then((token) => {\n console.log(token.id); // Token to store\n console.log(JSON.stringify(token.data)); // Contains redacted bank data\n });\n'})}),"\n",(0,r.jsx)(n.h4,{id:"2-tokenize-multiple-values-at-once",children:"2. Tokenize Multiple Values at Once"}),"\n",(0,r.jsxs)(n.p,{children:["The ",(0,r.jsx)(n.code,{children:"tokenize"})," method allows you to create multiple tokens in a single operation:"]}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-javascript",children:'// Tokenize multiple pieces of data at once\nbt.tokenize({\n // Create two card tokens with different approaches\n card1: {\n type: "card",\n data: cardElement, // Using the combined card element\n },\n card2: {\n type: "card",\n data: {\n // Using individual card elements\n number: cardNumberElement,\n expiration_month: cardExpirationDateElement.month(),\n expiration_year: cardExpirationDateElement.year(),\n cvc: cardVerificationCodeElement,\n },\n },\n // Create a generic token\n sensitiveData: sensitiveDataElement,\n \n // Include non-sensitive data\n nonSensitiveData: "plainText",\n otherData: {\n someInteger: 20,\n someBoolean: false,\n },\n someOtherData: ["plainText1", "plainText2"],\n}).then((tokens) => {\n // Multiple token IDs returned in the response\n console.log(tokens.card1.id, tokens.card2.id, tokens.sensitiveData);\n \n // Full response with all tokens\n console.log(JSON.stringify(tokens));\n});\n'})}),"\n",(0,r.jsx)(n.h3,{id:"updating-tokens",children:"Updating Tokens"}),"\n",(0,r.jsx)(n.p,{children:"You can update existing tokens with new values from Elements:"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-javascript",children:'// Update an existing token with a new value\nbt.tokens\n .update("ca9f3fd7-3906-4087-83aa-9a6129221297", { // Token ID to update\n data: cardElement, // New data from an element\n })\n .then((token) => {\n // Response contains redacted/masked updated data\n console.log(JSON.stringify(token.data));\n });\n'})}),"\n",(0,r.jsx)(n.h3,{id:"creating-token-intents",children:"Creating Token Intents"}),"\n",(0,r.jsx)(n.p,{children:"Token Intents provide a way to create tokens that require additional verification before being usable:"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-javascript",children:'// Create a token intent for a card\nbt.tokenIntents\n .create({\n type: "card",\n data: cardElement // Pass the card element\n })\n .then((tokenIntent) => {\n // Use this ID to validate and convert to a token\n console.log(tokenIntent.id); \n });\n\n// Alternative: Create with individual elements\nbt.tokenIntents\n .create({\n type: "card",\n data: {\n number: cardNumberElement,\n expiration_month: cardExpirationDateElement.month(),\n expiration_year: cardExpirationDateElement.year(),\n cvc: cardVerificationCodeElement\n }\n })\n .then((tokenIntent) => {\n console.log(tokenIntent.id);\n });\n'})}),"\n",(0,r.jsx)(n.h2,{id:"data-encryption",children:"Data Encryption"}),"\n",(0,r.jsx)(n.h3,{id:"encrypting-data",children:"Encrypting Data"}),"\n",(0,r.jsxs)(n.p,{children:["Basis Theory Elements can securely encrypt sensitive data using a public key and Key ID created through ",(0,r.jsx)(n.a,{href:"/docs/api/client-keys",children:"Encryption Keys"}),".\nThe ",(0,r.jsx)(n.code,{children:"tokens.encrypt"})," method enables encryption of data payloads, transforming sensitive information into encrypted JSON Web Encryption (JWE) strings."]}),"\n",(0,r.jsxs)(n.p,{children:["The ",(0,r.jsx)(n.code,{children:"tokens.encrypt"})," method accepts data objects containing element instances and plaintext payloads. It also supports encrypting multiple nested token payloads within a single operation."]}),"\n",(0,r.jsx)(n.h4,{id:"1-encrypt-a-single-token-payload",children:"1. Encrypt a Single Token Payload"}),"\n",(0,r.jsxs)(n.p,{children:["The ",(0,r.jsx)(n.code,{children:"tokens.encrypt"})," method encrypts a single token payload with your sensitive data:"]}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-javascript",children:'// Encrypt a token payload containing sensitive data\nbt.tokens\n .encrypt({\n tokenRequests: {\n type: "token", // Specify the token type\n data: {\n // Include element instances containing sensitive data\n sensitiveData: sensitiveDataElement, // Data remains in secure iframe\n \n // Include non-sensitive data directly\n nonSensitiveData: "plainText", \n \n // Nested data structures are supported\n otherData: {\n someInteger: 20,\n someBoolean: false,\n },\n someOtherData: ["plainText1", "plainText2"],\n },\n },\n publicKeyPem: "-----BEGIN PUBLIC KEY-----\\nw6RFs74UmOcxjbWBSlZQ0...=\\n-----END PUBLIC KEY-----",\n keyId: "d6b86549-212f-4bdc-adeb-2f39902740f6" // Key identifier\n })\n .then((response) => {\n // Response contains encrypted JWE string\n console.log(response.encrypted); // JWE encrypted payload\n console.log(response.type); // Token type\n \n // No sensitive data exposed - only encrypted string\n console.log(JSON.stringify(response)); \n });\n'})}),"\n",(0,r.jsx)(s.F,{type:s.W.INFO,children:"Note that the original data property will not appear in the response, maintaining secure data handling."}),"\n",(0,r.jsx)(n.h4,{id:"encrypt-a-card-token-payload",children:"Encrypt a Card Token Payload"}),"\n",(0,r.jsxs)(n.p,{children:["For payment card data, you can encrypt card payloads using either the combined ",(0,r.jsx)(n.code,{children:"CardElement"})," or individual card elements:"]}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-javascript",children:'// Option 1: Using the combined CardElement\nbt.tokens\n .encrypt({\n tokenRequests: {\n type: "card", // Specific type for cards\n data: cardElement, // Pass the entire card element\n },\n publicKeyPem: "-----BEGIN PUBLIC KEY-----\\nw6RFs74UmOcxjbWBSlZQ0...=\\n-----END PUBLIC KEY-----",\n keyId: "d6b86549-212f-4bdc-adeb-2f39902740f6"\n })\n .then((response) => {\n console.log(response.encrypted); // Encrypted card data as JWE\n console.log(response.type); // "card"\n });\n\n// Option 2: Using individual card elements\nbt.tokens\n .encrypt({\n tokenRequests: {\n type: "card",\n data: {\n // Each piece of card data in a separate element\n number: cardNumberElement,\n expiration_month: cardExpirationDateElement.month(), // Using the data parsing method\n expiration_year: cardExpirationDateElement.year(),\n cvc: cardVerificationCodeElement\n }\n },\n publicKeyPem: "-----BEGIN PUBLIC KEY-----\\nw6RFs74UmOcxjbWBSlZQ0...=\\n-----END PUBLIC KEY-----",\n keyId: "d6b86549-212f-4bdc-adeb-2f39902740f6"\n })\n .then((response) => {\n console.log(response.encrypted); // Encrypted card data as JWE\n console.log(response.type); // "card"\n });\n'})}),"\n",(0,r.jsx)(n.h4,{id:"2-encrypt-multiple-token-payloads-at-once",children:"2. Encrypt Multiple Token Payloads at Once"}),"\n",(0,r.jsxs)(n.p,{children:["The ",(0,r.jsx)(n.code,{children:"tokens.encrypt"})," method allows you to encrypt multiple token payloads in a single operation by nesting them under object keys:"]}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-javascript",children:'// Encrypt multiple token payloads at once\nbt.tokens\n .encrypt({\n tokenRequests: {\n // Create two card token payloads with different approaches\n tokenA: {\n type: "card",\n data: cardElement, // Using the combined card element\n },\n tokenB: {\n type: "card",\n data: {\n // Using individual card elements\n number: cardNumberElement,\n expiration_month: cardExpirationDateElement.month(),\n expiration_year: cardExpirationDateElement.year(),\n cvc: cardVerificationCodeElement,\n },\n },\n // Create a generic token payload\n tokenC: {\n type: "token",\n data: {\n sensitiveData: sensitiveDataElement,\n nonSensitiveData: "plainText",\n otherData: {\n someInteger: 20,\n someBoolean: false,\n },\n someOtherData: ["plainText1", "plainText2"],\n },\n },\n },\n publicKeyPem: "-----BEGIN PUBLIC KEY-----\\nw6RFs74UmOcxjbWBSlZQ0...=\\n-----END PUBLIC KEY-----",\n keyId: "d6b86549-212f-4bdc-adeb-2f39902740f6"\n })\n .then((response) => {\n // Multiple encrypted payloads returned in the response\n console.log(response.tokenA.encrypted); // Encrypted card A data\n console.log(response.tokenB.encrypted); // Encrypted card B data\n console.log(response.tokenC.encrypted); // Encrypted generic data\n \n // Each response includes the token type\n console.log(response.tokenA.type); // "card"\n console.log(response.tokenB.type); // "card"\n console.log(response.tokenC.type); // "token"\n \n // Full response with all encrypted payloads\n console.log(JSON.stringify(response));\n });\n'})}),"\n",(0,r.jsx)(n.h2,{id:"data-retrieval",children:"Data Retrieval"}),"\n",(0,r.jsx)(n.h3,{id:"retrieving-and-displaying-tokenized-data",children:"Retrieving and Displaying Tokenized Data"}),"\n",(0,r.jsxs)(n.p,{children:["To securely retrieve and display tokenized data, use the ",(0,r.jsx)(n.code,{children:"tokens.retrieve"})," method with the Element's ",(0,r.jsx)(n.code,{children:"setValue"})," method:"]}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-javascript",children:'// First, create an element to display the data\nconst textElement = bt.createElement("text", {\n targetId: "text-element",\n});\n\n// Retrieve the token and set its value into the element\nbt.tokens\n .retrieve("ca9f3fd7-3906-4087-83aa-9a6129221297", {\n apiKey: "<SESSION_API_KEY>", // Session key with appropriate permissions\n })\n .then((token) => {\n // Set the tokenized data into the element\n textElement.setValue(token.data);\n });\n'})}),"\n",(0,r.jsxs)(s.F,{type:s.W.WARNING,children:["The ",(0,r.jsx)("code",{children:"data"})," attribute in the token returned by ",(0,r.jsx)("code",{children:"retrieve"})," is not the actual data, but a synthetic representation. The real sensitive data remains secure within the Element."]}),"\n",(0,r.jsxs)(s.F,{children:["Non-sensitive token attributes like ",(0,r.jsx)("code",{children:"metadata"})," are directly accessible from the response."]}),"\n",(0,r.jsx)(n.h3,{id:"displaying-card-data",children:"Displaying Card Data"}),"\n",(0,r.jsx)(n.p,{children:"For card data, you can populate either a combined CardElement or individual card elements:"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-javascript",children:'// Option 1: Display in a combined CardElement\nconst cardElement = bt.createElement("card");\n\nbt.tokens\n .retrieve("ca9f3fd7-3906-4087-83aa-9a6129221297", {\n apiKey: "<SESSION_API_KEY>",\n })\n .then((token) => {\n // Set the entire card data object\n cardElement.setValue(token.data);\n });\n\n// Option 2: Display in individual elements\nconst cardNumberElement = bt.createElement("cardNumber", {\n targetId: "card-number",\n});\nconst cardExpirationDateElement = bt.createElement("cardExpirationDate", { \n targetId: "card-expiration-date" \n});\n\nbt.tokens\n .retrieve("ca9f3fd7-3906-4087-83aa-9a6129221297", {\n apiKey: "<SESSION_API_KEY>",\n })\n .then((token) => {\n // Set each piece into the appropriate element\n cardNumberElement.setValue(token.data.number);\n cardExpirationDateElement.setValue({\n month: token.data.expiration_month,\n year: token.data.expiration_year,\n });\n });\n'})}),"\n",(0,r.jsx)(n.h2,{id:"session-management",children:"Session Management"}),"\n",(0,r.jsx)(n.p,{children:"Sessions provide a secure way to grant temporary elevated access to tokenized data on the frontend, enabling features like:"}),"\n",(0,r.jsxs)(n.ul,{children:["\n",(0,r.jsx)(n.li,{children:"Displaying masked card data to users"}),"\n",(0,r.jsx)(n.li,{children:"Allowing users to update saved payment methods"}),"\n",(0,r.jsx)(n.li,{children:"Verifying identity with sensitive information"}),"\n"]}),"\n",(0,r.jsxs)(n.p,{children:[(0,r.jsx)(n.a,{href:"/docs/concepts/access-controls#what-are-sessions",children:"Learn more about sessions and access controls"}),"."]}),"\n",(0,r.jsx)(n.h3,{id:"creating-sessions",children:"Creating Sessions"}),"\n",(0,r.jsx)(n.p,{children:"You can create a new session for a Public Application:"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-javascript",children:"// Create a session for temporary elevated access\nconst session = await bt.sessions.create();\n"})}),"\n",(0,r.jsxs)(s.F,{children:["Sessions ",(0,r.jsx)("strong",{children:"cannot be authorized"})," directly from the frontend. All session authorization must be performed by a Private Application on your backend. This security measure prevents unauthorized access to sensitive data."]}),"\n",(0,r.jsx)(n.h2,{id:"third-party-integration",children:"Third-Party Integration"}),"\n",(0,r.jsx)(n.h3,{id:"proxy-service",children:"Proxy Service"}),"\n",(0,r.jsx)(n.p,{children:"The Proxy Service allows you to securely forward Element data to third-party APIs without exposing the sensitive data to your application."}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-javascript",children:'// Create elements for the request and response\nconst submitElement = bt.createElement("text", {\n targetId: "submitElement", // Element containing data to send\n});\nconst revealElement = bt.createElement("text", {\n targetId: "revealElement", // Element to display the response\n});\n\n// Make a POST request through the proxy\nbt.proxy\n .post({\n headers: {\n "BT-PROXY-KEY": "e29a50980ca5", // Your pre-configured proxy key\n },\n body: {\n sensitiveValue: submitElement, // Element containing sensitive data\n nonSensitiveValue: "plainText", // Regular data\n },\n apiKey: "<SESSION_API_KEY>", // Session key with appropriate permissions\n })\n .then((response) => {\n // Display the response data in the reveal element\n revealElement.setValue(response.value);\n });\n'})}),"\n",(0,r.jsx)(s.F,{type:s.W.WARNING,children:"The proxy response object is a synthetic representation of sensitive data, not the actual data. The real sensitive data remains secure within the Element."}),"\n",(0,r.jsx)(n.h4,{id:"supported-http-methods",children:"Supported HTTP Methods"}),"\n",(0,r.jsx)(n.p,{children:"The Proxy Service supports all standard HTTP methods:"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-javascript",children:"// GET request\nbt.proxy.get(options);\n\n// POST request\nbt.proxy.post(options);\n\n// PUT request\nbt.proxy.put(options);\n\n// PATCH request\nbt.proxy.patch(options);\n\n// DELETE request\nbt.proxy.delete(options);\n"})}),"\n",(0,r.jsx)(n.h4,{id:"proxy-request-options",children:"Proxy Request Options"}),"\n",(0,r.jsxs)(n.table,{children:[(0,r.jsx)(n.thead,{children:(0,r.
2jsxs)(n.tr,{children:[(0,r.jsx)(n.th,{children:"Option"}),(0,r.jsx)(n.th,{children:"Type"}),(0,r.jsx)(n.th,{children:"Required"}),(0,r.jsx)(n.th,{children:"Description"})]})}),(0,r.jsxs)(n.tbody,{children:[(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"path"})}),(0,r.jsx)(n.td,{children:"string"}),(0,r.jsx)(n.td,{children:"No"}),(0,r.jsx)(n.td,{children:"String appended to the end of the proxied URL path"})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"query"})}),(0,r.jsx)(n.td,{children:"object"}),(0,r.jsx)(n.td,{children:"No"}),(0,r.jsx)(n.td,{children:"Key/value pairs added as query parameters"})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"headers"})}),(0,r.jsx)(n.td,{children:"object"}),(0,r.jsx)(n.td,{children:"No"}),(0,r.jsx)(n.td,{children:"Key/value pairs added as HTTP headers"})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"body"})}),(0,r.jsx)(n.td,{children:"object"}),(0,r.jsx)(n.td,{children:"No"}),(0,r.jsx)(n.td,{children:"Payload sent to the proxied URL (can contain Elements)"})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"apiKey"})}),(0,r.jsx)(n.td,{children:"string"}),(0,r.jsx)(n.td,{children:"No"}),(0,r.jsxs)(n.td,{children:["BasisTheory API Key for ",(0,r.jsx)(n.a,{href:"/docs/api/authentication",children:"authentication"})]})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"correlationId"})}),(0,r.jsx)(n.td,{children:"string"}),(0,r.jsx)(n.td,{children:"No"}),(0,r.jsxs)(n.td,{children:["ID for ",(0,r.jsx)(n.a,{href:"/docs/api/request-correlation",children:"request correlation"})]})]}),(0,r.jsxs)(n.tr,{children:[(0,r.jsx)(n.td,{children:(0,r.jsx)(n.code,{children:"idempotencyKey"})}),(0,r.jsx)(n.td,{children:"string"}),(0,r.jsx)(n.td,{children:"No"}),(0,r.jsxs)(n.td,{children:["Key for request ",(0,r.jsx)(n.a,{href:"/docs/api/idempotency",children:"idempotency"})]})]})]})]}),"\n",(0,r.jsx)(n.h4,{id:"accessing-non-sensitive-proxy-responses",children:"Accessing Non-Sensitive Proxy Responses"}),"\n",(0,r.jsx)(o.Ay,{}),"\n",(0,r.jsx)(n.h3,{id:"http-client-service",children:"HTTP Client Service"}),"\n",(0,r.jsx)(n.p,{children:"The HTTP Client Service enables you to make requests to third-party APIs with Element data in the payload:"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-javascript",children:'// Initialize BasisTheory\nconst bt = await basistheory("<API_KEY>");\n\n// Make a POST request with sensitive data\nbt.client.post(\n "https://www.api.thirdpartydomain.com/resources",\n {\n sensitiveData: sensitiveDataElement, // Element containing sensitive data\n nonSensitiveData: "plainText",\n otherData: {\n someInteger: 20,\n someBoolean: false,\n }\n },\n {\n headers: {\n "Content-Type": "application/json"\n }\n }\n).then((response) => {\n // Full plaintext response is accessible\n console.log(JSON.stringify(response));\n});\n'})}),"\n",(0,r.jsx)(l.Ay,{}),"\n",(0,r.jsx)(n.h4,{id:"supported-http-methods-1",children:"Supported HTTP Methods"}),"\n",(0,r.jsx)(n.p,{children:"The HTTP Client Service supports all standard HTTP methods:"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-javascript",children:"// GET request\nbt.client.get(url, options);\n\n// POST request\nbt.client.post(url, body, options);\n\n// PUT request\nbt.client.put(url, body, options);\n\n// PATCH request\nbt.client.patch(url, body, options);\n\n// DELETE request\nbt.client.delete(url, options);\n"})}),"\n",(0,r.jsx)(n.h2,{id:"error-handling",children:"Error Handling"}),"\n",(0,r.jsx)(n.h3,{id:"basis-theory-service-errors",children:"Basis Theory Service Errors"}),"\n",(0,r.jsx)(n.p,{children:"When using Basis Theory services, you may encounter two main types of errors:"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-javascript",children:'import { BasisTheoryApiError, BasisTheoryValidationError } from "@basis-theory/web-elements/common";\n\nbt.tokenize({\n card1: {\n type: "card",\n data: cardElement1,\n },\n card2: {\n type: "card",\n data: cardElement2,\n },\n ssn: textElement,\n}).catch((error) => {\n if (error instanceof BasisTheoryValidationError) {\n // Client-side validation failure\n // Example: incomplete or invalid element data\n console.error("Validation error:", error.details);
2\n \n // Check specific field errors\n if (error.details.card1?.number?.type === \'invalid\') {\n // Handle invalid card number\n }\n } else if (error instanceof BasisTheoryApiError) {\n // Server-side error\n console.error(`API error ${error.status}:`, error.data);\n }\n});\n'})}),"\n",(0,r.jsx)(n.h3,{id:"http-client-service-errors",children:"HTTP Client Service Errors"}),"\n",(0,r.jsx)(n.p,{children:"HTTP client services can throw similar validation errors, plus HTTP-specific errors:"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-javascript",children:'import { HttpClientError, BasisTheoryValidationError } from "@basis-theory/web-elements/common";\n\nconst bt = await basistheory("<API_KEY>");\n\nbt.client.post(\n "https://api.example.com/data",\n {\n sensitiveData: textElement,\n }\n).catch((error) => {\n if (error instanceof BasisTheoryValidationError) {\n // Client-side validation failure\n console.error("Validation error:", error.details);\n } else if (error instanceof HttpClientError) {\n // HTTP error from the third-party API\n console.error(`HTTP error ${error.status}:`, error.data);\n console.log("Response headers:", error.headers);\n }\n});\n'})}),"\n",(0,r.jsx)(n.h3,{id:"error-types-reference",children:"Error Types Reference"}),"\n",(0,r.jsx)(n.h4,{id:"basistheoryvalidationerror",children:"BasisTheoryValidationError"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-javascript",children:"{\n name: \"BasisTheoryValidationError\",\n details: {\n card1: {\n number: {\n type: 'invalid' // The field is invalid\n },\n cvc: {\n type: 'incomplete' // The field is not complete\n }\n },\n card2: {\n // No issues with card2\n }\n },\n validation: [] // deprecated\n}\n"})}),"\n",(0,r.jsx)(n.h4,{id:"basistheoryapierror",children:"BasisTheoryApiError"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-javascript",children:'{\n name: "BasisTheoryApiError",\n data: {\n // Full API response body from Basis Theory\n },\n status: 400 // HTTP status code\n}\n'})}),"\n",(0,r.jsx)(n.h4,{id:"httpclienterror",children:"HttpClientError"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-javascript",children:'{\n name: "HttpClientError",\n data: {\n // Response body from the third-party API\n },\n status: 400, // HTTP status code\n headers: {\n // Response headers from the third-party API\n }\n}\n'})}),"\n",(0,r.jsxs)(s.F,{children:["You can check the error ",(0,r.jsx)("code",{children:"name"})," property as an alternative to using ",(0,r.jsx)("code",{children:"instanceof"})," for type checking."]}),"\n",(0,r.jsx)(l.Ay,{}),"\n",(0,r.jsx)(s.F,{type:s.W.INFO,children:(0,r.jsxs)(n.p,{children:["If you encounter issues during tokenization such as timeout errors or validation failures, refer to our ",(0,r.jsx)(n.a,{href:"/docs/sdks/web/web-elements/troubleshooting",children:"troubleshooting guide"})," for detailed solutions."]})})]})}function m(e={}){const{wrapper:n}={...(0,i.R)(),...e.components};return n?(0,r.jsx)(n,{...e,children:(0,r.jsx)(u,{...e})}):u(e)}},21020:(e,n,t)=>{var a=t(96540),r=Symbol.for("react.element"),i=Symbol.for("react.fragment"),s=Object.prototype.hasOwnProperty,o=a.__SECRET_INTERNALS_DO_NOT_USE_OR_YOU_WILL_BE_FIRED.ReactCurrentOwner,l={key:!0,ref:!0,__self:!0,__source:!0};function d(e,n,t){var a,i={},d=null,c=null;for(a in void 0!==t&&(d=""+t),void 0!==n.key&&(d=""+n.key),void 0!==n.ref&&(c=n.ref),n)s.call(n,a)&&!l.hasOwnProperty(a)&&(i[a]=n[a]);if(e&&e.defaultProps)for(a in n=e.defaultProps)void 0===i[a]&&(i[a]=n[a]);return{$$typeof:r,type:e,key:d,ref:c,props:i,_owner:o.current}}n.Fragment=i,n.jsx=d,n.jsxs=d},74848:(e,n,t)=>{e.exports=t(21020)},85202:(e,n,t)=>{t.d(n,{F:()=>D,W:()=>P});var a=t(34164),r=t(96540);const i="container_ygYU",s="title_KE4f",o="content_mpoX",l="error_YPD5",d="warning_Vv3u",c="info_XpSc",p="success_pFpA",h="neutral_bgLU",u="svg_xN_H";var m;function y(){return y=Object.assign?Object.assign.bind():function(e){for(var n=1;n<arguments.length;n++){var t=arguments[n];for(var a in t)({}).hasOwnProperty.call(t,a)&&(e[a]=t[a])}return e},y.apply(null,arguments)}const v=e=>{let{title:n,titleId:t,...a}=e;return r.createElement("svg",y({xmlns:"http://www.w3.org/2000/svg",width:18,height:18,fill:"none",viewBox:"0 0 18 18","aria-labelledby":t},a),n?r.createElement("title",{id:t},n):null,m||(m=r.createElement("path",{fill:"#F56C9D",fillRule:"evenodd",d:"M9 1.438A7.557 7.557 0 0 0 1.438 9 7.557 7.557 0 0 0 9 16.563 7.56 7.56 0 0 0 16.563 9 7.56 7.56 0 0 0 9 1.438M.063 9A8.93 8.93 0 0 1 9 .063 8.937 8.937 0 0 1 17.938 9 8.937 8.937 0 0 1 9 17.938 8.93 8.93 0 0 1 .063 9M9 4.188c.38 0 .688.307.688.687v4.583a.687.687 0 1 1-1.376 0V4.875c0-.38.308-.687.688-.687m-.006 7.791H9q.034 0 .067.003c.444.038.85.4.85.914 0 .27-.122.496-.272.645a.92.92 0 0 1-.645.271.92.92 0 0 1-.917-.916.914.914 0 0 1 .908-.917z",clipRule:"evenodd"})))};var x,g;function j(){return j=Object.assign?Object.assign.bind():function(e){for(var n=1;n<arguments.length;n++){var t=arguments[n];for(var a in t)({}).hasOwnProperty.call(t,a)&&(e[a]=t[a])}return e},j.apply(null,arguments)}const f=e=>{let{title:n,titleId:t,...a}=e;return r.createElement("svg",j({xmlns:"http://www.w3.org/2000/svg",width:20,height:18,fill:"none",viewBox:"0 0 20 18","aria-labelledby":t},a),n?r.createElement("title",{id:t},n):null,x||(x=r.createElement("path",{fill:"#FFA726",fillRule:"evenodd",d:"M7.656 1.614c1.04-1.809 3.649-1.809 4.689 0l7.055 12.27c1.037 1.803-.264 4.053-2.344 4.053H2.945c-2.08 0-3.381-2.25-2.345-4.052zm3.497.685a1.33 1.33 0 0 0-2.305 0L1.792 14.57a1.33 1.33 0 0 0 1.153 1.992h14.111a1.33 1.33 0 0 0 1.152-1.992z",clipRule:"evenodd"})),g||(g=r.createElement("path",{fill:"#FFA726",fillRule:"evenodd",d:"M10.001 5.883c.38 0 .688.308.688.688v3.428a.687.687 0 1 1-1.376 0V6.571c0-.38.308-.688.688-.688m-.006 6.183H10q.034 0 .068.003c.443.038.849.4.849.914 0 .27-.122.496-.271.645A.92.92 0 0 1 10 13.9a.92.92 0 0 1-.917-.916.914.914 0 0 1 .908-.917z",clipRule:"evenodd"})))};var b,E;function k(){return k=Object.assign?Object.assign.bind():function(e){for(var n=1;n<arguments.length;n++){var t=arguments[n];for(var a in t)({}).hasOwnProperty.call(t,a)&&(e[a]=t[a])}return e},k.apply(null,arguments)}const T=e=>{let{title:n,titleId:t,...a}=e;return r.createElement("svg",k({xmlns:"http://www.w3.org/2000/svg",width:18,height:18,fill:"none",viewBox:"0 0 18 18","aria-labelledby":t},a),n?r.createElement("title",{id:t},n):null,b||(b=r.createElement("path",{fill:"#00B68A",fillRule:"evenodd",d:"M5.58.743a8.937 8.937 0 1 1 6.84 16.514A8.937 8.937 0 0 1 5.58.743M9 1.438a7.562 7.562 0 1 0 0 15.124A7.562 7.562 0 0 0 9 1.437",clipRule:"evenodd"})),E||(E=r.createElement("path",{fill:"#00B68A",fillRule:"evenodd",d:"M12.664 6.31c.268.268.269.703 0 .972l-4.34 4.35a.69.69 0 0 1-1.087.151l-.018-.018L5.25 9.797a.688.688 0 1 1 .972-.972l1.481 1.481 3.987-3.995a.69.69 0 0 1 .973-.001",clipRule:"evenodd"})))};var w,S;function N(){return N=Object.assign?Object.assign.bind():function(e){for(var n=1;n<arguments.length;n++){var t=arguments[n];for(var a in t)({}).hasOwnProperty.call(t,a)&&(e[a]=t[a])}return e},N.apply(null,arguments)}const I=e=>{let{title:n,titleId:t,...a}=e;return r.createElement("svg",N({xmlns:"http://www.w3.org/2000/svg",width:18,height:18,fill:"none",viewBox:"0 0 18 18","aria-labelledby":t},a),n?r.createElement("title",{id:t},n):null,w||(w=r.createElement("path",{fill:"#29B6F6",fillRule:"evenodd",d:"M9.45 4.966a.69.69 0 0 0-.587-.33.914.914 0 0 0-.917.917.92.92 0 0 0 .917.917c.27 0 .495-.122.645-.271a.92.92 0 0 0 .271-.646.69.69 0 0 0-.33-.587M7.396 12.208c0-.38.308-.687.687-.687h2.118a.687.687 0 1 1 0 1.375H8.083a.69.69 0 0 1-.687-.688",clipRule:"evenodd"})),S||(S=r.createElement("path",{fill:"#29B6F6",fillRule:"evenodd",d:"M5.58.743a8.937 8.937 0 1 1 6.84 16.514A8.937 8.937 0 0 1 5.58.743M9 1.438a7.562 7.562 0 1 0 0 15.124A7.562 7.562 0 0 0 9 1.437m-.495 4.479a.687.687 0 0 0 1.265-.373.91.91 0 0 0-.97-.905.687.687 0 0 0-.295 1.278m-1.1 2.396c0-.38.307-.688.687-.688h1.054c.38 0 .687.308.687.688v3.895a.687.687 0 1 1-1.375 0V9h-.366a.69.69 0 0 1-.688-.687",clipRule:"evenodd"})))};var P=function(e){return e.ERROR="error",e.WARNING="warning",e.INFO="info",e.SUCCESS="success",e.NEUTRAL="neutral",e}({});const D=({type:e="info",title:n,content:t,children:m})=>{const y=(0,a.A)({[l]:"error"==e,[d]:"warning"==e,[c]:"info"==e,[p]:"success"==e,[h]:"neutral"==e}),x={error:v,warning:f,info:I,success:T}[e];return r.createElement("div",{className:(0,a.A)([i,y,"alert"])},x&&r.createElement("div",null,r.createElement(x,{className:u})),r.createElement("div",null,n&&r.createElement("div",{className:s},n),r.createElement("div",{className:o},null!=t?t:m)))}},28453:(e,n,t)=>{t.d(n,{R:()=>s,x:()=>o});var a=t(96540);const r={},i=a.createContext(r);function s(e){const n=a.useContext(i);return a.useMemo((function(){return"function"==typeof e?e(n):{...n,...e}}),[n,e])}function o(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(r):e.components||r:s(e.components),a.createElement(i.Provider,{value:n},e.children)}}}]);
Line numbers count LF bytes from the start of the resource, as the search results do. Vendor segments are library code the classifier recognised; they are stored but not indexed. Bytes are shown as Latin1 characters, one per byte.