How does URBLD API authentication work?
URBLD uses OAuth 2.0. Server-to-server integrations and AI agents use the client_credentials grant. Third-party apps that act on behalf of a URBLD user use authorization_code with PKCE. Access tokens are bearer tokens scoped to one organization and one or more of 17 granular scopes (leads.read, jobs.write, etc.).
Grant types
client_credentials (recommended for AI agents)
Use when your code acts as itself — a backend service, cron job, or autonomous agent bound to one organization.
bash
curl -X POST https://api.urbld.com/v1/oauth/token \
-d "grant_type=client_credentials" \
-d "client_id=$URBLD_CLIENT_ID" \
-d "client_secret=$URBLD_CLIENT_SECRET" \
-d "scope=leads.read jobs.write"authorization_code + PKCE
Use when a URBLD user needs to grant your third-party app delegated access to their organization.
- Redirect the user to
https://api.urbld.com/v1/oauth/authorizewithresponse_type=code,client_id,redirect_uri,scope,state, and PKCEcode_challenge. - URBLD redirects back to your
redirect_uriwith a short-livedcode. - Exchange the code at the token endpoint with
grant_type=authorization_codeand your PKCEcode_verifier.
Using the token
http
GET /v1/customers/42 HTTP/1.1
Host: api.urbld.com
Authorization: Bearer eyJhbGciOi...Scopes
Request only the scopes you need. URBLD's authorization screen shows the user exactly which scopes your app is requesting.
| Scope | Grants |
|---|---|
| leads.read | Read leads and lead activity. |
| leads.write | Create, update, and convert leads. |
| customers.read | Read customer records and lifecycle history. |
| customers.write | Create and update customer records. |
| scheduling.read | Read availability, appointments, and dispatch state. |
| scheduling.write | Book, reschedule, and cancel appointments. |
| estimates.read | Read estimates and line items. |
| estimates.write | Create and update estimates. |
| contracts.read | Read contract packages and e-sign status. |
| contracts.write | Send contract packages for signature. |
| jobs.read | Read job records from contract through warranty. |
| jobs.write | Update job state, notes, and attachments. |
| invoices.read | Read invoices and AR aging. |
| invoices.write | Issue and update invoices. |
| payments.read | Read payments and receipts. |
| communications.read | Read unified inbox threads. |
| communications.write | Send SMS and email messages. |
Security requirements
- Never embed
client_secretin mobile or browser apps. Use PKCE without a secret for public clients. - Rotate secrets at least every 90 days.
- Always validate the
stateparameter to prevent CSRF on the authorization_code flow. - Store tokens in a secure server-side store — never in
localStorage.
FAQ
Frequently Asked Questions
Straight answers about how URBLD runs the business end-to-end.