Latest version of CERB API OAuth2 real-world examples

[bencarrasco]

Anyone have some examples (curl and php would be awesome) of using Oauth2 REST API? Running into inconsistent results. If the examples could be against the demo database, that would be even better.

-Regards, BC

[jstanden]

Hi @bencarrasco!

With PHP you can use GuzzleHttp or cURL directly. Once you have an OAuth2 token you just include it in the Authorization: Bearer <token> header.

If it's a low-risk scenario (e.g. creating tickets from a web form), that token could be manually generated and long-lived (months). You'd rotate it occasionally.

If it's a higher-risk scenario (e.g. PII customer data) then it's best to stick with the 1-hour expiring access token and use the refresh token to replace it.

This is a great OAuth2 client library for PHP, but it might be overkill for a simple API script:
https://github.com/thephpleague/oauth2-client

I recommend using something like Paw https://paw.cloud or Postman https://www.postman.com to test the API. They'll handle the OAuth2 for you so you can spend your time actually making requests.

When you create an OAuth App in Cerb (Search->OAuth Apps) you'll define scopes like:

"profile":
 label: Access your profile information
 endpoints:
  - workers/me: GET

"search":
 label: Search records on your behalf
 endpoints:
  - records/*/search: [GET]

"api:read-only":
 label: Make any read-only API request on your behalf
 endpoints:
  - "*": [GET]

"api":
 label: Make any API request on your behalf
 endpoints:
  - "*" #[GET, PATCH, POST, PUT, DELETE]

Use that to generate a test token from Setup->Developers->OAuth2 Generator:

You'll get back a relatively long JWT token starting like eyJ0eXAiOiJKV1...

With cURL from the CLI, you can make a simple request like GET /rest/workers/me.json:

curl -H "Authorization: eyJ0eXAiOiJKV[...]" https://cerb.example/rest/workers/me.json | jq

You get back the JSON "dictionary" of your worker:

{
  "__build": 2022110401,
  "__status": "success",
  "__version": "10.3.3",
  "_context": "cerberusweb.contexts.worker",
  "_image_url": "https://cerb.example/avatars/worker/1?v=1667265299",
  "_label": "Kina Halpue",
  "_type": "worker",
  "address_id": 1,
  "address_org__context": "cerberusweb.contexts.org",
  "address_org__type": "org",
  "at_mention_name": "Kina",
  "calendar__context": "cerberusweb.contexts.calendar",
  "calendar__type": "calendar",
  "calendar_id": 7,
  "dob": null,
  "first_name": "Kina",
  "full_name": "Kina Halpue",
  "gender": "F",
  "id": 1,
  "is_disabled": 0,
  "is_superuser": 1,
  "language": "en_US",
  "last_name": "Halpue",
  "location": "Los Angeles, CA, USA",
  "mobile": "+7146719090",
  "phone": "",
  "record_url": "https://cerb.example/profiles/worker/1-Kina-Halpue",
  "time_format": "D, d M Y h:i a",
  "timeout_idle_secs": 86400,
  "timezone": "America/Los_Angeles",
  "title": "Customer Service Manager",
  "updated": 1667265299,
  "time_format": "D, d M Y h:i a",
  "timeout_idle_secs": 86400,
  "timezone": "America/Los_Angeles",
  "title": "Customer Service Manager",
  "updated": 1667265299
}

If you want to create a new task:

curl -X POST -H "Authorization: eyJ0eXAiOiJK[...]" -d 'fields[title]=Check+out+Cerb' https://cerb.example/rest/records/task/create.json | jq

This returns the JSON dictionary of the new task:

{
  "__build": 2022110401,
  "__status": "success",
  "__version": "10.3.3",
  "_context": "cerberusweb.contexts.task",
  "_label": "Check out Cerb",
  "_type": "task",
  "completed": 0,
  "created": 1668204180,
  "due": 0,
  "id": "1234",
  "importance": 50,
  "is_completed": false,
  "owner__context": "cerberusweb.contexts.worker",
  "owner_id": 0,
  "record_url": "https://cerb.example/profiles/task/1234-Check-out-Cerb",
  "reopen": 0,
  "status": "open",
  "status_id": 0,
  "title": "Check out Cerb",
  "updated": 1668204180
}

Let me know if there are any specific examples you'd like.

[bencarrasco]

After following the first example, I receive the following error:

{"__status":"error","message":"Unauthorized request"}

[jstanden]

Can you share the request you're making, and the scopes you set up in the OAuth App in Cerb?

Did you use the OAuth2 Token Generator as a test, or was this with an actual OAuth client to manage the refresh token?

When you pass the token in Authorization: Bearer <token> it's pretty large. Make sure you include the entire thing.

I suspect the issue will be permissions via the scope.

In my example OAuth app above there's an api scope that can use the entire API with every verb. That's good for testing; but in production you'd want to use a "least privileges" scope for just the necessary endpoints. The api:read-only scope shows an example of that.

When you generate a test token from Setup->Developers, make sure you include a scope like api from the app you set up to permit the endpoints. The api scope is a good one to test with to verify everything works otherwise. Then you can lock it down.

I'm happy to help continue troubleshooting until you get everything working.