- Overview
- Introduction to Cal.com Atoms
- Setup
- Apple calendar connect
- Availability settings
- Booker Embed
- Booker
- Bookings hooks
- Cal OAuth Provider
- Cal Provider
- Calendar settings
- Calendar view
- Calendars hooks
- Conferencing Apps
- Create schedule
- Event Type
- Event types hooks
- FAQ
- Google calendar connect
- List Event Types
- List schedules
- Onboarding Embed
- Outlook calendar connect
- Payment form
- Quickstart
- Stripe Connect
- Troubleshooter
- User / Teams hooks
- Bookings hooks
- Calendars hooks
- Event types hooks
- FAQ
- Introduction
- Quickstart
- User / Teams hooks
- Apple calendar connect
- Availability settings
- Booker Embed
- Booker
- Cal OAuth Provider
- Cal Provider
- Calendar settings
- Calendar view
- Conferencing Apps
- Create schedule
- Event Type
- Google calendar connect
- List Event Types
- List schedules
- Outlook calendar connect
- Payment form
- Stripe Connect
- Troubleshooter
- Managing booking fields
- Booking redirects
- Custom booking flow
- Custom slot selection flow
- Global event types
- Managed organizations
- Custom toasts
- Configuring your team
Managed organizations
Archived Cal.com Atoms documentation for Managed organizations. These deprecated SDK components are no longer maintained.
This is now deprecated and under maintenance for existing users only - no new customers can sign up for the platform plan
1. How to create a managed organization
First, manually create an OAuth client in https://app.cal.com/settings/platform.
Second, make a POST request to https://api.cal.com/v2/organizations/:organizationId/organizations to create a managed organization and receive its API key:
- Replace
:organizationIdin the URL with your organization Id that you can copy from OAuth client settings. - Add authentication headers
x-cal-client-idequal to OAuth client id andx-cal-secret-keyequal to the OAuth client secret. - Add request body
{
"name": "some organization",
"metadata": {
"some": "metadata"
},
"apiKeyDaysValid": 60
}Required fields: "name" - name of the managed organization.
Optional fields: "metadata", "apiKeyDaysValid", "apiKeyNeverExpires". By default the API key of a managed organization is valid for 30 days which means that you have to rotate them (will explain how below). If you want that API key is valid, for example, 60 days then specify that using "apiKeyDaysValid: 60" or if you want that API key never expires, set "apiKeyNeverExpires: true" in the request body.
Here is response:
{
"status": "success",
"data": {
"id": 148,
"name": "some organization",
"metadata": {
"some": "metadata"
},
"apiKey": "cal_xxx168ceb89117cc3a1b1f1777511506"
}
}Notably, you will only have access to the apiKey now, so make sure to create a table in your database where you store managed organization's id and apiKey . The apiKey will be used to create an OAuth client that is used to create platform users.
Using same x-cal-client-id and x-cal-secret-key headers you can make requests to:
- Fetch managed organization by making GET request to
https://api.cal.com/v2/organizations/:organizationId/organizations/:managedOrganizationId - Fetch all managed organizations by making GET request to
https://api.cal.com/v2/organizations/:organizationId/organizations - Update managed organization by making PATCH request to
https://api.cal.com/v2/organizations/:organizationId/organizations/:managedOrganizationIdwith body where you can specify either "name" or "metadata" - Delete managed organization by making DELETE request to
https://api.cal.com/v2/organizations/:organizationId/organizations/:managedOrganizationId
Shortly, the flow is that using OAuth credentials of manager organization you create a managed organization and using its API key you can create and managed OAuth clients of the managed organization, and for the rest of the things like creating "managed users" of managed organization you will use OAuth client credentials.
2. How to create OAuth client for a managed organization
Now that you have created a managed organization and have its apiKey you can create OAuth clients for the managed organization.
Make POST request to https://api.cal.com/v2/oauth-clients by:
- Setting
Authorization: Bearer <apiKey>header where<apiKey>is API key returned when creating a managed organization. - Setting request body:
- name is name of the OAuth client
- permissions - an array that can receive following permissions:
"EVENT_TYPE_READ", "EVENT_TYPE_WRITE", "BOOKING_READ", "BOOKING_WRITE", "SCHEDULE_READ", "SCHEDULE_WRITE", "APPS_READ", "APPS_WRITE", "PROFILE_READ", "PROFILE_WRITE"or if you want all of them enabled set*. You most probably want to use*. See docs here https://cal.com/docs/platform/quickstart#2-setting-up-an-oauth-client - redirectUris - point to (as example)
your-domain.com*where users end up when connecting google calendar etc and what is the origin of the requests aka what origins are allowed to make requests to our endpoints. Havingyour-domain.com*would mean that we will accept requests from cal UI components that make requests fromyour-domain.com, your-domain.com/pageetc.
{
"name": "OAuth client for managed organization",
"redirectUris": ["https://your-domain.com*"],
"permissions": ["*"]
}Response:
{
"status": "success",
"data": {
"clientId": "xxxepq3bg0000khghtq4bxxx",
"clientSecret": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.example-client-secret-payload.example-signature"
}
}Using the same Authorization: Bearer <apiKey> header, you can also:
- Fetch all OAuth clients: GET
https://api.cal.com/v2/oauth-clients - Fetch a specific OAuth client: GET
https://api.cal.com/v2/oauth-clients/:oAuthClientId
3. How to refresh API key of a managed organization
If you did not specify apiKeyNeverExpires when creating a managed organization then you will have to refresh the API key after apiKeyDaysValid (if you specified it) or by default after 30 days.
Make a POST request to https://api.cal.com/v2/api-keys/refresh by:
- Setting
Authorization: Bearer <apiKey>header where<apiKey>is API key returned when creating a managed organization. - Add a request body
{"apiKeyDaysValid": 30}or whatever number of days you want the new API key to be valid or{"apiKeyNeverExpires": true}if you want that it never expires.
The response will contain the new API key for the managed organization:
{
"status": "success",
"data": {
"apiKey": "cal_xxx467709fffebe8c6559211cb5f178f"
}
}and now you have to update in your database API key of the managed organization.
Last updated