Authentication
You must provide an Origin header to tell the API which platform the request belongs to (e.g. https://sugarblock.io).
Signing in
Call userLogin with the user's email, password and a valid captchaToken. We use Google reCAPTCHA Enterprise to prove that a person using a browser is signing in, without showing them a challenge. Generate it in the browser with grecaptcha.enterprise.execute, passing the platform's reCAPTCHA site key and the authentication action.
If the user has two-factor authentication enabled, send the current one-time code in otp in the same call. The API limits sign-in attempts per IP address.
const captchaToken = await grecaptcha.enterprise.execute(SITE_KEY, { action: 'authentication' })
const response = await fetch('https://api.guita.cl/graphql', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
query: `mutation UserLogin($email: String!, $password: String!, $captchaToken: String!, $otp: String) {
userLogin(email: $email, password: $password, captchaToken: $captchaToken, otp: $otp) {
credentials { accessToken client uid provider expiry }
}
}`,
variables: { email: 'user@example.com', password: 'secret', captchaToken, otp: '123456' }
})
})
const { data } = await response.json()
const { credentials } = data.userLogin
Users registered with Google sign in with googleSignIn instead.
Authenticated requests
A successful sign-in returns credentials. Send these four values as headers on every authenticated request, along with Origin:
access-token: the credential's accessTokenclient: the credential's clientuid: the credential's uidprovider: the credential's provider (email or google)
Every authenticated response may carry new values for access-token, client, uid and expiry in its headers, but not every response includes all of them. Requests sent within a few seconds of each other share the same token, and their responses return an empty access-token and expiry. After each response, overwrite only the values that come back non-empty and keep the stored ones for the rest.
The expiry value is the time when the current token stops being valid. After that, the user must sign in again.
Errors and signing out
A missing or invalid token is replied with HTTP 200 and an error with code AUTHENTICATION_ERROR. For example, querying accountInformation without a valid token returns:
{
"errors": [
{
"message": "accountInformation field requires authentication",
"locations": [{ "line": 1, "column": 28 }],
"path": ["accountInformation"],
"extensions": { "code": "AUTHENTICATION_ERROR" }
}
],
"data": null
}
Call userLogout to invalidate the current token.
Verification
Users must be manually verified before they can operate. Every user goes through a KYC or KYB flow where they provide their information and documents, then submit them for review. Our compliance team may request additional information in specific cases, so approval is never immediate. The Uploads guide explains how to upload documents.
Mandatory steps for every account
- Confirm the email address with a confirmation link sent to the user's email address after they sign up.
- Choose with updateUserType whether the account belongs to an individual or a business. This choice cannot be changed later.
- Complete a liveness check using the FaceTec SDK, which communicates with our server through facetecProcessRequest.
Required information for individuals
Required information for businesses
- Company identity information (updateBusinessIdentity).
- Legal address information (updateLegalAddress), plus a proof of address (createAddressProof).
- Expected trading activity (updateTransactionProfile).
- Company documents uploaded with createBusinessProof. Depending on the company's legal structure, the following documents are required (see below for more details on each document type):
- Companies formed outside Chile:
BANK_ACCOUNT, VALIDITY_CERTIFICATE, TAX_REGISTRATION_CERTIFICATE and COMPANY_CONSTITUTION.
- Chilean companies registered under EUD (Empresa en un Día):
BANK_ACCOUNT, VALIDITY_CERTIFICATE, E_RUT, TAX_FILE and UPDATED_STATUTES.
- Chilean companies registered under CSR (Registro de Comercio):
BANK_ACCOUNT, VALIDITY_CERTIFICATE, E_RUT, TAX_FILE, COMPANY_CONSTITUTION, GAZETTE_PUBLICATION, CSR_INSCRIPTION and POWER_OF_ATTORNEY, plus BOARD_OF_DIRECTORS for corporations.
- Ultimate beneficial owners, at least one of them with the
LEGAL_REPRESENTATIVE role. The legal representative scans their identity document with FaceTec, and the scan creates them as an owner (see below). Add the other owners with createUltimateBeneficialOwner and upload their identity documents with createIdentityProofs. Every owner, including the legal representative, also needs a proof of address uploaded with createAddressProof. Pass the owner's uboId to both mutations.
Company documents:
| documentType | Document |
|---|
BANK_ACCOUNT | Proof of the company's bank account, such as a statement or an account certificate. No more than 90 days old. |
VALIDITY_CERTIFICATE | Certificate of the company's current legal standing, issued by the commercial registry. No more than 60 days old. |
TAX_REGISTRATION_CERTIFICATE | Tax registration certificate, issued by the tax authority. |
COMPANY_CONSTITUTION | Public deed of incorporation. |
E_RUT | Current electronic RUT card, issued by the SII. |
TAX_FILE | Tax file (carpeta tributaria) issued by the SII for credit applications. No more than 6 months old. |
UPDATED_STATUTES | The company's current bylaws. No more than 90 days old. |
GAZETTE_PUBLICATION | Extract of incorporation published in the Diario Oficial. |
CSR_INSCRIPTION | Registration in the commercial registry, issued by the Conservador de Bienes Raíces. No more than 60 days old. |
POWER_OF_ATTORNEY | Certificate of current powers of attorney, issued by the Conservador. No more than 60 days old. |
BOARD_OF_DIRECTORS | Current list of the board of directors. |
SOCIAL_MODIFICATION | Optional. Deed, extract and registration of each amendment to the company's bylaws. |
Scanning the identity document with FaceTec
After the liveness check, the user scans their identity document with the FaceTec SDK. For a business, the legal representative does the liveness check and the scan. The scan goes through the same facetecProcessRequest mutation.
The photo on the document must match the user's selfie, or the scan fails with INSUFFICIENT_MATCH_LEVEL. An expired document fails with INVALID_EXPIRATION_DATE. A successful scan stores the document images and replaces any stored before.
If the user has no personal identity yet, the scan fills in the name, nationality and identification number from the document. For a business with no beneficial owners yet, the scan creates the legal representative with that data, so scan before adding the other owners. Complete the rest of the information with updatePersonIdentity or, for the legal representative, updateUltimateBeneficialOwner.
Submitting for review
Once everything is complete, call updateVerification. While the submission is under review, the API locks the user's information and mutations that change it fail with IDENTITY_NOT_EDITABLE.
In some cases compliance asks for more information, such as the origin of the user's funds and wealth. The user declares them with createFundOrigin and createWealthOrigin and uploads supporting documents.
Query accountInformation to follow the process through its accountStatus:
| accountStatus | What the user should do |
|---|
EMAIL_UNCONFIRMED | Confirm their email address. |
IDENTITY_UNVERIFIED | Complete their information and submit it. |
IDENTITY_PENDING_REVIEW | Wait for compliance to review the submission. |
IDENTITY_PENDING_CHANGES | Correct the information requested by compliance, then submit again. |
IDENTITY_PENDING_MORE_CHANGES | Provide the additional information requested by compliance, then submit again. |
IDENTITY_REJECTED | Nothing. Compliance did not approve the account. |
IDENTITY_VERIFIED | Nothing. The account is verified. |
The user receives an email every time compliance approves, rejects or requests changes. When compliance requests changes, the email says what to correct.
Uploads
Files do not go through GraphQL. Uploading a document takes three steps:
- Create the document with its
create mutation, declaring the file's content type. The response includes a StoragePost in storagePost.
- Send the file to
storagePost.url in a multipart/form-data POST request. Add every pair from fieldsKeys and fieldsValues as a form field, in order, and the file last, in a field named file.
- Confirm the upload with the matching
update mutation. The document does not count as uploaded until this step succeeds.
For example, in a browser:
const uploadToStorage = (storagePost, file) => {
const form = new FormData()
storagePost.fieldsKeys.forEach((key, index) => (
form.append(key, storagePost.fieldsValues[index])
))
form.append('file', file)
return fetch(storagePost.url, { method: 'POST', body: form })
}
Documents
Things to keep in mind
- Files can be up to 16 MiB.
- The upload must start within 3 minutes of calling the
create mutation. Querying storagePost again does not extend that window; create the document again instead.
- The file must have the content type declared when creating the document.
- Browsers can only upload from the platform's web address, the same one sent as
Origin in API requests.
- Some documents replace the previous ones when created again. For example, createIdentityProofs and createAddressProof delete the documents created before for the same person.
- To read a document back, query its
storageUrl. It is empty until you confirm the upload, and each URL is valid for 10 minutes.