Authentication and keys

Every request carries one API key in the Authorization header:

Authorization: Bearer dl_live_7Kx2mQ9pR4tV8wY1zA3cE5gH6jL0nP2sU4xB7dF9

Keys in the URL (?api_key=…) are refused with 400 api_key_in_query. If you sent one that way, treat the key as exposed and rotate it.

Test and live keys

A test key can never read or change a real landlord's data, and a live key can never reach a sandbox. Each response says which mode served it in the X-DOOLAE-Mode header.

Creating, rotating and revoking keys

Create keys in the portal under API keys. Each key belongs to one application and has:

• a name;
• a mode;
• scopes: a subset of the application's;
• an optional expiry;
• for live keys, optionally one bound account.

Live keys need a linked account. You can create a live key only after at least one DOOLAE account is linked to the application. Until then the portal shows Link DOOLAE Account instead, and the server refuses the request even if it is sent another way.

DOOLAE stores only a fingerprint (an HMAC) of each key, so a key is shown exactly once and can't be recovered.

• Rotate creates a new key with the same settings. The old key keeps working for 24 hours, so you can deploy the new one without downtime.
• Revoke stops a key at once. Use it as soon as you suspect a key leaked.

The portal shows when each key was last used.

Scopes

Each endpoint requires one scope:

A request may use a scope only when the key has it, the application asks for it, and the landlord granted it. Otherwise it gets 403 insufficient_scope, and the response names the required scope.

Ask only for what you need. Landlords see the list on the consent page. If you add scopes to an application later, landlords who connected earlier keep their original grant until they approve again.

Accounts

GET /v1/properties
Authorization: Bearer dl_live_xxxxxxxxx
DOOLAE-Account: acct_01JYYY

DOOLAE-Account selects an account that has already authorized your application. Knowing an account ID alone doesn't grant access. On every request DOOLAE checks, in order:

1. the API key;
2. its application;
3. an active link between that application and the account;
4. the scopes on the key, the application and the landlord's grant;
5. that the property, room, tenant or bill belongs to that account.

If the account isn't linked to your application, the answer is 403 account_not_connected. That is the same answer whether the account exists or not.

IDs are identifiers, not credentials

Treat all of them as public. A property or room ID from another account answers 404 resource_not_found, even with a valid key and a linked account.

Choosing the account

A live request acts on exactly one landlord account. There are three ways it is chosen:

• A key bound to one account acts on that account. Nothing else is needed.

• An unbound live key must name the account on every request:

  DOOLAE-Account: acct_cm2x8k1qz0001a8b3c4d5e6f7
  

  Without it, the request gets 403 account_required.

• A test key always acts on the application's sandbox.

GET /v1/account returns the account a request reaches, its DOOLAE plan features, and the scopes usable there.

Errors you may see:

Linking DOOLAE accounts

From the portal

On the application's page, open Linked DOOLAE accounts and choose Link DOOLAE Account.

1. The portal sends you to DOOLAE's consent page. The account's owner signs in to DOOLAE and sees:

   • your application and company;
   • each requested scope;
   • which account it is, with its number of properties and rooms.

2. When the owner chooses อนุญาต (Allow), DOOLAE sends the browser back to the portal with a single-use code. The code is valid for 5 minutes.

3. The portal exchanges the code and creates the link. The exchange checks:

   • your signed-in developer session;
   • the state cookie of the browser that started the request.

   A replayed or forged callback is refused.

4. The account then appears under Linked DOOLAE accounts with its account ID, properties, property IDs, room counts, scopes and status. You can now create live keys.

If you signed in to the portal with the same Google account you use on DOOLAE, the portal offers that account first. You still approve on DOOLAE: nothing is ever linked automatically.

Your customers' accounts

The flow above finishes in the browser that started it. For landlords who use your own app, send them the connect link from your app. It is on the application's page in the portal:

https://doolae.online/connect/app_…?redirect_uri=https%3A%2F%2Fexample.com%2Fdoolae%2Fconnected&state=RANDOM

1. The landlord signs in to DOOLAE and sees your application name, your company, what each scope allows (in Thai), and what you can never do.
2. On approval, DOOLAE redirects to your redirect_uri with account_id=acct_…&state=RANDOM. On denial, the parameters are error=access_denied&state=RANDOM.
3. The redirect_uri must exactly match one you registered for the application. DOOLAE never redirects anywhere else.
4. Generate a fresh random state for each link, and check it when the landlord comes back.

Disconnecting

Either side can end a link, and it takes effect on the very next request:

• You, with Disconnect on the account in the portal.
• The landlord, with ยกเลิกการเชื่อมต่อ (Disconnect) at doolae.online/settings/apps.

Requests for that account then get 403 account_access_revoked. Other linked accounts are not affected. The landlord's data is never deleted. Linking again needs the owner's approval again.

Developer and application status