OneCal Unified is currently in BETA. This means that the API is not finalized and is subject to change. If you have any questions, please contact us at contact@onecalunified.com.

End User Accounts

An End User Account in OneCal Unified represent a user's calendar account from a specific provider that has been authenticated with your application.

An End User Account can contain multiple calendars.

The End User Account model

Properties

  • Name
    id
    Type
    string
    Description

    Unique identifier for the end user account.

  • Name
    createdAt
    Type
    timestamp
    Description

    Timestamp of when the end user account was created.

  • Name
    updatedAt
    Type
    timestamp
    Description

    Timestamp of when the end user account was last updated.

  • Name
    email
    Type
    string
    Description

    Email address of the end user.

  • Name
    externalId
    Type
    string?
    Description

    Custom ID for the end user account if provided.

  • Name
    authorizedScopes
    Type
    string[]
    Description

    List of authorized scopes granted by the end user account to the application.

  • Name
    providerAccountId
    Type
    string?
    Description

    The ID of the account in the provider's system, if applicable.

  • Name
    applicationId
    Type
    string
    Description

    Identifier of the application associated with this end user account.

  • Name
    status
    Type
    enum
    Description

    Status of the end user account. Possible values: ACTIVE, EXPIRED. See End User Account Status for more information.

  • Name
    providerType
    Type
    enum
    Description

    Type of the provider associated with this end user account. Possible values: GOOGLE, MICROSOFT.

End User Account Status

End User Accounts may move to an EXPIRED status if the refresh token is no longer valid. While the user is in this status, you will not be able to access calendars or events associated with the End User Account. The refresh token may expire for a variety of reasons, including:

  • The user has revoked access to the application
  • Automatically after some time for security reasons
  • The refresh token has been revoked by the provider
  • The user has changed their account password
  • The user's organization has has had a policy change that requires the user to re-authenticate
  • The user has been deleted

If an End User Account is in an EXPIRED status, you can refresh the credentials through one of two ways:

  1. By sending a request to the POST /v1/endUserAccounts endpoint with the same email and providerType as the End User Account you want to refresh.
  2. By redirecting the user to the same authentication flow described in the End User Authentication guide. We recommend providing the email through the loginHint query parameter for this flow.
GET/v1/endUserAccounts

List End User Accounts

This endpoint retrieves a paginated list of all End User Accounts associated with your application.

Optional query parameters

  • Name
    search
    Type
    string
    Description

    Filter end user accounts by email or external ID.

Request

GET
/v1/endUserAccounts
curl -X GET https://api.onecalunified.com/api/v1/endUserAccounts \
  -H "x-api-key: {apiKey}"

Response

{
  "data": [
    {
      "id": "user_account_1",
      "createdAt": "2025-09-10T13:22:35.983Z",
      "updatedAt": "2025-09-10T13:22:35.983Z",
      "email": "johndoe@example.com",
      "externalId": "",
      "authorizedScopes": [
        "openid",
        "email",
        "profile",
        "User.Read",
        "Calendars.ReadWrite"
      ],
      "providerAccountId": "johndoe_provider_account_id",
      "providerId": "provider_1",
      "applicationId": "application_1",
      "status": "ACTIVE",
      "providerType": "MICROSOFT"
    },
    {
      "id": "user_account_2",
      "createdAt": "2025-09-08T15:33:20.209Z",
      "updatedAt": "2025-09-08T15:33:20.209Z",
      "email": "johndoe@example.com",
      "externalId": "",
      "authorizedScopes": [
        "email",
        "profile",
        "https://www.googleapis.com/auth/calendar.events",
        "https://www.googleapis.com/auth/calendar",
        "https://www.googleapis.com/auth/userinfo.profile",
        "https://www.googleapis.com/auth/userinfo.email",
        "openid"
      ],
      "providerAccountId": "johndoe_provider_account_id",
      "providerId": "provider_2",
      "applicationId": "application_1",
      "status": "ACTIVE",
      "providerType": "GOOGLE"
    }
  ],
  "nextPageToken": null
}
GET/v1/endUserAccounts/:id

Get End User Account

This endpoint returns the details of a specific End User Account associated with your application.

Path parameters

  • Name
    id
    Type
    string
    Description

    The unique identifier of the End User Account to retrieve.

Request

GET
/v1/endUserAccounts/:id
curl -X GET https://api.onecalunified.com/api/v1/endUserAccounts/user_account_1 \
  -H "x-api-key: {apiKey}"

Response

{
  "id": "user_account_1",
  "createdAt": "2025-09-10T13:22:35.983Z",
  "updatedAt": "2025-09-10T13:22:35.983Z",
  "email": "johndoe@example.com",
  "externalId": "",
  "authorizedScopes": [
    "openid",
    "email",
    "profile",
    "User.Read",
    "Calendars.ReadWrite"
  ],
  "providerAccountId": "johndoe_provider_account_id",
  "providerId": "provider_1",
  "applicationId": "application_1",
  "status": "ACTIVE",
  "providerType": "MICROSOFT"
}
GET/v1/endUserAccounts/:id/credentials

Get End User Account Credentials

This endpoint returns the credentials of a specific End User Account associated with your application. This is useful if you need to retrieve to the access token or refresh token of an end user account, so you can perform operations on your end.

Path parameters

  • Name
    id
    Type
    string
    Description

    The unique identifier of the End User Account whose credentials you want to retrieve.

Request

GET
/v1/endUserAccounts/:id/credentials
curl -X GET https://api.onecalunified.com/api/v1/endUserAccounts/user_account_1/credentials \
  -H "x-api-key: {apiKey}"

Response

{
    "id": "cmgfcdwez001joo2gpvl4dbmn",
    "endUserAccountId": "cmgfcdwer001hoo2g6wgyrqqp",
    "accessToken": "token",
    "refreshToken": "token",
    "expiresAt": "2025-10-14T12:02:05.334Z",
    "status": "ACTIVE",
    "createdAt": "2025-10-06T16:25:24.059Z",
    "updatedAt": "2025-10-14T11:02:06.335Z"
}
POST/v1/endUserAccounts

Create or Update End User Account

An End User Account is automatically created when a user authenticates your application through the steps outlined in the End User Authentication guide.

It is also possible to manually create an End User Account for a user by sending an API request. This is useful for when you want to sync your existing authorized users with OneCal Unified, or for when you want full control over the OAuth2 flow.

This endpoint can also be used to update the credentials of an existing End User Account.

Request body

  • Name
    email
    Type
    string
    Description

    The email address of End User Account you want to create or update.

  • Name
    externalId
    Type
    string?
    Description

    Set or update the external ID of the End User Account (optional).

  • Name
    providerType
    Type
    enum
    Description

    The type of provider of the End User Account you want to create or update. Possible values: GOOGLE, MICROSOFT.

  • Name
    refreshToken
    Type
    string
    Description

    The refresh token received from the Provider for the End User Account you want to create or update.

Request

POST
/v1/endUserAccounts
curl https://api.onecalunified.com/api/v1/endUserAccounts \
  -H "x-api-key: {apiKey}" \
  -H "Content-Type: application/json" \
  -d '{"email": "johndoe@email.com", "externalId": "1234567890", "providerType": "MICROSOFT", "refreshToken": "refresh_token"}'

Response

{
  "id": "user_account_1",
  "createdAt": "2025-09-10T13:22:35.983Z",
  "updatedAt": "2025-09-10T13:22:35.983Z",
  "email": "johndoe@example.com",
  "externalId": "1234567890",
  "authorizedScopes": [
    "openid",
    "email",
    "profile",
    "User.Read",
    "Calendars.ReadWrite"
  ],
  "providerAccountId": "johndoe_provider_account_id",
  "providerId": "provider_1",
  "applicationId": "application_1",
  "status": "ACTIVE",
  "providerType": "MICROSOFT"
}
DELETE/v1/endUserAccounts/:id

Delete End User Account

This endpoint deletes an existing End User Account.

Path parameters

  • Name
    id
    Type
    string
    Description

    The unique identifier of the End User Account to be deleted.

Request

DELETE
/v1/endUserAccounts/:id
curl -X DELETE https://api.onecalunified.com/api/v1/endUserAccounts/user_account_1 \
  -H "x-api-key: {apiKey}"

Response

{
  "message": "End User Account deleted",
  "ok": true
}

Was this page helpful?