UserInfo

Required plan: Starter

Description #

Returns identifying information for the authenticated account. This is defined as part of the OpenID spec.

URL format #

{data_center_url}/v1/userinfo

Example Request #

GET /v1/userinfo HTTP/1.1
Host: {data_center_url}
Authorization: Bearer {ACCESS_TOKEN}

Example Response #

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "sub": "acc_5700a00eb0ccd07000000000",
  "email": "janed@company.com",
  "name": "Jane Doe",
  "zoneinfo": "Europe/London",
  "cronofy.type": "account",
  "cronofy.data": {
    "authorization": {
      "scope": "read_write",
      "status": "active"
    },
    "profiles": [
      {
        "provider_name": "google",
        "provider_service": "gsuite",
        "profile_id": "pro_n23kjnwrw2",
        "profile_name": "example1@cronofy.com",
        "profile_connected": true,
        "profile_initial_sync_required": true,
        "profile_calendars": [
          {
            "calendar_id": "cal_n23kjnwrw2_jsdfjksn234",
            "calendar_name": "Home",
            "calendar_readonly": false,
            "calendar_deleted": false,
            "calendar_primary": true,
            "permission_level": "sandbox"
          },
          {
            "calendar_id": "cal_n23kjnwrw2_n1k323nkj23",
            "calendar_name": "Work",
            "calendar_readonly": true,
            "calendar_deleted": true,
            "calendar_primary": false,
            "permission_level": "sandbox"
          }
        ]
      },
      {
        "provider_name": "apple",
        "provider_service": "icloud",
        "profile_id": "pro_fe145c37de",
        "profile_name": "example2@cronofy.com",
        "profile_connected": false,
        "profile_initial_sync_required": false,
        "profile_relink_url": "https://app.cronofy.com/relink/apple?email=example@cronofy.com",
        "profile_calendars": [
          {
            "calendar_id": "cal_fe145c37de_3nkj23wejk1",
            "calendar_name": "Bank Holidays",
            "calendar_readonly": true,
            "calendar_deleted": false,
            "calendar_primary": false,
            "permission_level": "sandbox"
          }
        ]
      }
    ]
  }
}

Request parameters #

data_center_url required

The URL for the data center you want to communicate with. Possible choices are:

  • api-au.cronofy.com - πŸ‡¦πŸ‡Ί Australia
  • api-ca.cronofy.com - πŸ‡¨πŸ‡¦ Canada
  • api-de.cronofy.com - πŸ‡©πŸ‡ͺ Germany
  • api-sg.cronofy.com - πŸ‡ΈπŸ‡¬ Singapore
  • api-uk.cronofy.com - πŸ‡¬πŸ‡§ United Kingdom
  • api.cronofy.com - πŸ‡ΊπŸ‡Έ United States

Find out more about Cronofy's data centers.

Response parameters #

sub  #

This specifies the internal Cronofy ID for the account, as an ASCII-only String.

email optional  #

The primary email address associated with the account as a String.

When the account is a Service Account, this value may represent a username instead of a full email address. For example, when authenticating a Service Account via Active Directory username and password.

name optional  #

The name associated with the account as a String. May be null or blank.

zoneinfo optional  #

A String representing a known time zone identifier from the IANA Time Zone Database.

Common examples are:

  • Etc/UTC
  • Europe/Paris
  • America/Chicago
cronofy.type  #

This specifies the type of the account as a String.

This can be used to know the format of data that can be expected within cronofy.data.

cronofy.data  #

A custom structure within which detail information about the authorization and account are provided.

cronofy.data.authorization  #

Includes information relating to the authenticated authorization.

cronofy.data.authorization.scope  #

This specifies the scope granted for the account for the active authorization as a space-separated String in order to mimic how it is provided during an Authorization Request.

cronofy.data.authorization.status  #

The current status of the authorization. Currently two possible values are supported.

  • active - your authorization to their Account is active and their Profiles are actively being synced.
  • hibernated - your authorization to their Account is currently in a hibernated state. Using this Account in a qualifying API call will trigger the status to switch to active and Profile syncing to be activated.
cronofy.data.profiles optional  #

Details of the calendar profiles associated with the account, where relevant.

cronofy.data.profiles.provider_name  #

This specifies the provider of the calendar as a lowercase, ASCII-only String.

Currently one of:

  • apple
  • cronofy
  • exchange
  • google
  • live_connect

However, this will be expanded over time and therefore consumers should support any value for this field.

cronofy.data.profiles.provider_service  #

This specifies the service that hosts the calendar as a lowercase, ASCII-only String.

Currently one of:

  • cronofy
  • exchange
  • google
  • gsuite
  • icloud
  • office365
  • outlook_com

However, this will be expanded over time and therefore consumers should support any value for this field.

This should be used to help a user distinguish between their profiles as they can have multiple profiles with the same name.

cronofy.data.profiles.profile_id  #

This specifies the ID of the profile, a profile may consist of many calendars, as an ASCII-only String.

This is used for targeting other API actions toward this profile.

cronofy.data.profiles.profile_name  #

This specifies the name of the profile as a String.

cronofy.data.profiles.profile_connected  #

This specifies whether we have an active connection for this profile, usually whether we have valid credentials or not, as a Boolean.

cronofy.data.profiles.profile_initial_sync_required  #

This specifies whether we have performed an initial sync this profile, this is a function of the number of events, and therefore the quantity of data, in their calendar and can take between a few seconds and a few minutes from the accounts first connection.

> When the profile is not connected, a URL will be provided as a String that you can direct the user to in order for them to reconnect this profile.

This URL is unique to each profile as it contains information relating to the underlying provider and so forth.

cronofy.data.profiles.profile_calendars.calendar_id  #

This specifies the ID of the calendar as an ASCII-only String.

This is used for targeting other API actions toward this calendar.

cronofy.data.profiles.profile_calendars.calendar_name  #

This specifies the name of the calendar as a String.

This should be used to help a user distinguish between their calendars as they can have multiple calendars within the same profile.

cronofy.data.profiles.profile_calendars.calendar_readonly  #

This specifies whether the calendar is readonly as a Boolean.

Calendars where calendar_readonly is true will refuse requests to create, update, or delete events.

cronofy.data.profiles.profile_calendars.calendar_deleted  #

This specifies whether the calendar has been deleted as a Boolean.

Calendars where calendar_deleted is true will refuse requests to create, update, or delete events.

cronofy.data.profiles.profile_calendars.calendar_primary  #

This specifies whether the calendar is the primary calendar for its profile as a Boolean.

Current support by provider:

  • Apple has no concept of primary calendars
  • Exchange has a primary calendar which cannot change
  • Google has a primary calendar which cannot change
  • Office 365 has a primary calendar which cannot change
  • Outlook.com has a primary calendar which can change
cronofy.data.profiles.profile_calendars.calendar_integrated_conferencing_available  #

This specifies whether the calendar supports integrated conferencing as a Boolean. Currently this is only true for Google calendars which have Google Meet available.

cronofy.data.profiles.profile_calendars.permission_level  #

This value specifies the current permission level granted to the client for the specified calendar. Permitted values are currently either sandbox or unrestricted.

In order to perform a edit or delete on external events you must have unrestricted access to the calendar.

Application Calendar specific response parameters #

Relevent when cronofy.type is application_calendar.

cronofy.data.application_calendar.application_calendar_id  #

The String that uniquely identifies the application calendar.

Service Account specific response parameters #

Relevant when cronofy.type is service_account.

cronofy.data.service_account.provider_name  #

This specifies the provider of the service account as a lowercase, ASCII-only String.

Currently one of:

  • apple
  • cronofy
  • exchange
  • google
  • live_connect
cronofy.data.service_account.domain  #

The domain the service account relates to as an ASCII-only String.

We may not be able to determine this, and this property is not guaranteed to be populated.

cronofy.data.authorization.delegated_scope  #

This specifies the delegated scope granted for the service account for the active authorization as a space-separated String in order to mimic how it is provided during an Enterprise Connect Authorization Request.

Error responses #

401 Unauthorized #

The request was refused as the provided authentication credentials were not recognized.

When an OAuth refresh_token is available then it should be used to request a replacement access_token before the request is retried.