Services

Static Fields

You can set your API key globally for BasisTheoryElements through the static apiKey field.

BasisTheoryElements.apiKey = "<YOUR PUBLIC BT API KEY>"

All service method calls take an optional apiKey should you need to override the globally set apiKey.

The proxy service call does not use this globally set apiKey since its use case is different from the other services and requires a session API key for requests.

Methods

tokenize

Elements' values can be securely tokenized utilizing our tokenize services. To accomplish this, simply pass the Element instance in the payload.

let body: [String: Any] = [
  "data": [
    "property": <BasisTheory Element instance>,
    "myProp": "myValue"
  ],
  "search_indexes": ["{{ data.property }}"],
  "type": "token"
]

BasisTheoryElements.tokenize(body: body, apiKey: "<PUBLIC_API_KEY>")
  { data, error in ... }

Note that tokenize requires the use of a public API key (an API key issued to a public Application). Click here to create one in the Basis Theory portal.

The callback provided calls your function with a data of type AnyCodable, and an error of type Error.

createToken

Elements' values can be securely tokenized utilizing our createToken services. To accomplish this, simply pass the Element instance in the payload.

let body: CreateToken = CreateToken(type: "token", data: [
  "property": <BasisTheory Element instance>,
  "myProp": "myValue",
], searchIndexes: ["{{ data.property }}"])

BasisTheoryElements.createToken(body: body, apiKey: "<PUBLIC_API_KEY>")
  { data, error in ... }

Note that createToken requires the use of a public API key (an API key issued to a public Application). Click here to create one in the Basis Theory portal.

The callback provided calls your function with a data of type CreateTokenResponse, and an error of type Error.

createSession

To retrieve sensitive data on iOS, you'll need to create a session and use its sessionKey for making requests securely. To accomplish this, simply construct your createSession request like this:

BasisTheoryElements.createSession(
    apiKey: "<YOUR PUBLIC BT API KEY>"
) { data, error in ... }

The callback provided calls your function with a data of type CreateSessionResponse, and an error of type Error.

getTokenById

This function wraps the get a token API endpoint to retrieve a single strongly typed token. The token's data is transformed to value references which you can use to set the value of your elements without touching the plaintext value and pulling your application into compliance scope.

BasisTheoryElements.getTokenById(
    id: "<YOUR TOKEN ID>",
    apiKey: "<YOUR API KEY>",
) { data, error in ... }

The callback provided calls your function with a:

• error of type Error
• data of type JSON - JSON is a data structure that has dynamic member lookup capabilities. This allows you to traverse a token without giving you access to read any sensitive values in token.data which means you stay compliant.

To show a value from the token data, traverse the JSON using dot or bracket notation and retrieve the value using the elementValueReference property. Below is an example of how you do that and set the value reference into a Text Element.

@IBOutlet private weak var myTextElement: TextElementUITextField!
...

BasisTheoryElements.getTokenById(
    id: "<YOUR TOKEN ID>",
    apiKey: "<YOUR API KEY>",
) { data, error in
    myTextElement.setValue(elementValueReference: data!.data!.nested!.property!.elementValueReference)
}

proxy

Proxy provides a simple way to send data securely using an element and/or retrieve data back into an element utilizing our proxy service. To accomplish this, simply construct your proxy request like this:

@IBOutlet weak var testElement: TextElementUITextField!

let proxyHttpRequest = ProxyHttpRequest(method: .post, body: [
    "testProp": "testValue",
    "testElementPro": testElement,
    "objProp": [
        "nestedTestProp": "nestedTestValue"
    ]
], headers: [
    "X-My-Custom-Header": "headerValue",
])

BasisTheoryElements.proxy(
    apiKey: "<YOUR SESSION BT API KEY>",
    proxyKey: "<YOUR PROXY KEY>",
    proxyHttpRequest: proxyHttpRequest
) { response, data, error in ... }

Note that proxy requires the use of a sessionKey (an API key issued via createSession).

The callback provided calls your function with a:

• response of type URLResponse
• error of type Error
• data of type JSON

Below is an example of how you can use a response from a proxy with our elements.

@IBOutlet private weak var myTextElement: TextElementUITextField!
...

BasisTheoryElements.proxy(
    apiKey: "<YOUR SESSION BT API KEY>",
    proxyKey: "<YOUR PROXY KEY>",
    proxyHttpRequest: proxyHttpRequest)
{ response, data, error in
    myTextElement.setValue(elementValueReference: data.my?.nested?.property?.elementValueReference)

    let body: CreateToken = CreateToken(type: "token", data: [
        "myNestedProxyResponseProperty": myTextElement,
    ])
    BasisTheoryElements.createToken(body: body, apiKey: "<PUBLIC_API_KEY>")
    { data, error in print(data) }
}

Access non-sensitive responses from Proxy calls

Beta

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.

This feature is currently invite-only. If you're interested, please get in touch for an invitation.

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 www.basistheory.com/contact

HTTP Client Services

Element values can be used in a request to a third-party API using our HTTP client service.

post

The example below shows how to use the HTTP client service to make a POST request to a third-party API with an element in the payload.

Invoking HTTP Client Service w/ POST

@IBOutlet private weak var myTextElement: TextElementUITextField!

let payload = [
    "textElementProp": myTextElement,
    "plainTextProp": "plaintext value",
    "object" : [
        "nestedProp": "nested value"
    ],
    "array": [1, 2, 3]
] as [String : Any]
let config = Config(headers: [
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-Test-Header": "test header value"
])

BasisTheoryElements.post(url: "https://www.api.thirdpartydomain.com/resources", payload: payload, config: config) { request, data, error in
    print(data)
}

The response from this service is the actual plaintext data. It may contain sensitive data depending on the third-party API response.

The callback provided calls your function with a:

• response of type URLResponse
• error of type Error
• data of type JSON

put

The example below shows how to use the HTTP client service to make a PUT request to a third-party API with an element in the payload.

Invoking HTTP Client Service w/ PUT

@IBOutlet private weak var myTextElement: TextElementUITextField!

let payload = [
    "textElementProp": myTextElement,
    "plainTextProp": "plaintext value",
    "object" : [
        "nestedProp": "nested value"
    ],
    "array": [1, 2, 3]
] as [String : Any]
let config = Config(headers: [
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-Test-Header": "test header value"
])

BasisTheoryElements.put(url: "https://www.api.thirdpartydomain.com/resources/id", payload: payload, config: config) { request, data, error in
    print(data)
}

The response from this service is the actual plaintext data. It may contain sensitive data depending on the third-party API response.

The callback provided calls your function with a:

• response of type URLResponse
• error of type Error
• data of type JSON

patch

The example below shows how to use the HTTP client service to make a PATCH request to a third-party API with an element in the payload.

Invoking HTTP Client Service w/ PATCH

@IBOutlet private weak var myTextElement: TextElementUITextField!

let payload = [
    "textElementProp": myTextElement,
    "plainTextProp": "plaintext value",
    "object" : [
        "nestedProp": "nested value"
    ],
    "array": [1, 2, 3]
] as [String : Any]
let config = Config(headers: [
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-Test-Header": "test header value"
])

BasisTheoryElements.patch(url: "https://www.api.thirdpartydomain.com/resources/id", payload: payload, config: config) { request, data, error in
    print(data)
}

The response from this service is the actual plaintext data. It may contain sensitive data depending on the third-party API response.

The callback provided calls your function with a:

• response of type URLResponse
• error of type Error
• data of type JSON

get

The example below shows how to use the HTTP client service to make a GET request to a third-party API.

Invoking HTTP Client Service w/ GET

let config = Config(headers: [
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-Test-Header": "test header value"
])

BasisTheoryElements.get(url: "https://www.api.thirdpartydomain.com/resources/id", config: config) { request, data, error in
    print(data)
}

The response from this service is the actual plaintext data. It may contain sensitive data depending on the third-party API response.

The callback provided calls your function with a:

• response of type URLResponse
• error of type Error
• data of type JSON

delete

The example below shows how to use the HTTP client service to make a DELETE request to a third-party API.

Invoking HTTP Client Service w/ DELETE

let config = Config(headers: [
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-Test-Header": "test header value"
])

BasisTheoryElements.delete(url: "https://www.api.thirdpartydomain.com/resources/id", config: config) { request, data, error in
    print(data)
}

The response from this service is the actual plaintext data. It may contain sensitive data depending on the third-party API response.

The callback provided calls your function with a:

• response of type URLResponse
• error of type Error
• data of type JSON

JSON

JSON is a data structure that has dynamic member lookup capabilities. This means that you can traverse a JSON response using dot or bracket notation. Each property in a JSON struct returns a JSON struct has the following properties to help read sensitive and non-sensitive properties:

• elementValueReference - This property is used to get the sensitive value of a JSON property. It returns a value reference that can be used to set the value of an iOS Basis Theory element.
• rawValue - This property is used to get the non-sensitive value of a JSON property. It returns the plaintext value of the property.

Only numbers, booleans, and strings can be retrieved using this struct.

Errors

Error	Description
TokenizingError.applicationTypeNotPublic	The Application API key used is not of type public. Create a public API key through this link.
TokenizingError.invalidInput	An element instance used in a tokenization request is invalid. Check the element events on each element to determine which one is invalid.
ProxyError.invalidRequest	The proxy request is malformed. Revise the proxy request being attempted.
ErrorResponse.error	An instance of ErrorResponse enum gets returned when there's an error from the BasisTheory API.

ErrorResponse Enum

Order	Associated Value Name	Description
1	status	An Int describing the response status code
2	data	A Data? instance describing the response body
3	urlResponse	The raw UrlResponse? instance
4	error	The raw Error instance

The ErrorResponse enum can be imported from the BasisTheory Swift SDK through the BasisTheory package, which is a dependency of the iOS BasisTheoryElements package.