Calendars¶

The calendar endpoint is used to manage a user's calendars. Calendars can be used to track expiration dates of mytokens via ICS feeds that can be imported into calendar applications.

The URI of the calendar endpoint is constructed by appending /calendars to the notification endpoint which can be obtained from the configuration endpoint.

Get Calendar List¶

Calendar List Request¶

To get a list of the user's calendars, the client sends a GET request to the calendar endpoint. The request MUST include a mytoken with the read@manage_mytokens:notify capability as authorization.

Example

GET /api/v0/notifications/calendars HTTP/1.1
Host: mytoken.example.com
Authorization: Bearer eyJhbGcio...

Calendar List Response¶

A successful response returns the following parameters using the application/json media type:

Parameter	Necessity	Description
`calendars`	REQUIRED	A JSON array of calendar objects holding information about each calendar

The calendar object has the following attributes:

Parameter	Necessity	Description
`id`	REQUIRED	A unique identifier for the calendar
`ics_path`	REQUIRED	A URI where the calendar's ICS can be downloaded
`description`	OPTIONAL	A description of the calendar
`tags`	OPTIONAL	A JSON Array of TagInfo objects associated with the calendar
`subscribed_tokens`	REQUIRED if tokens are subscribed	A list of the mom ids of the tokens that are included in this calendar

Example

HTTP/1.1 200 OK
Content-Type: application/json

{
    "calendars": [
        {
            "id": "59ckwFkBdQoqo6t5jAkdnek24kd9HvUB",
            "ics_path": "https://mytoken.example.com/calendars/59ckwFkBdQoqo6t5jAkdnek24kd9HvUB",
            "description": "CI/CD pipeline tokens",
            "tags": [
                {
                    "tag": "CI",
                    "color": "#3357ff"
                }
            ],
            "subscribed_tokens": [
                "rB8g1NhHqRNQL8S38DkzQgMJ9Df7wVmnuX1dkSk3kAlsUQM6igudDWL3ZMYf4xm1AL8/pQdGAetBa/y5ktydrg==",
                "Kqi9Jvwz5v4QCpNGrx8oon5ZJmtQEZ+zK/s52ynWpUMkl4kjEMskeLL3RqTkhvC6FOk7mTs1tJPdLXPx8OZ+uQ=="
            ]
        },
        {
            "id": "wKDX3j1jal5kDkD2k4Jkl4tfunVJHlxw",
            "ics_path": "https://mytoken.example.com/calendars/wKDX3j1jal5kDkD2k4Jkl4tfunVJHlxw",
            "description": "Development tokens"
        }
    ]
}

Create Calendar¶

Create Calendar Request¶

To create a new calendar, the client sends a POST request to the calendar endpoint and adds the following parameters using the application/json or application/x-www-form-urlencoded format in the HTTP request entity-body:

Parameter	Necessity	Description
`mytoken`	REQUIRED	A mytoken used as authorization; MUST have the `manage_mytokens:notify` capability
`description`	OPTIONAL	A description for the calendar
`tags`	OPTIONAL	A JSON Array of tag names to associate with this calendar

Example

POST /api/v0/notifications/calendars HTTP/1.1
Host: mytoken.example.com
Content-Type: application/json

{
    "mytoken": "eyJhbGcio...",
    "description": "CI/CD pipeline tokens",
    "tags": ["CI", "production"]
}

Create Calendar Response¶

A successful response has the HTTP status code 201 and returns a single calendar object as described under Calendar List Response.

Example

HTTP/1.1 201 Created
Content-Type: application/json

{
    "id": "59ckwFkBdQojad93Daks3jk24kd9HvUB",
    "ics_path": "https://mytoken.example.com/calendars/59ckwFkBdQojad93Daks3jk24kd9HvUB",
    "description": "CI/CD pipeline tokens",
    "tags": [
        {
            "tag": "CI",
            "color": "#3357ff"
        },
        {
            "tag": "production",
            "color": "#ff5733"
        }
    ]
}

Get Calendar ICS¶

Calendar Info Request¶

To get a calendar's ICS data, a client sends a GET request to its ics_path. If the client did not already obtain the ics_path, it can send a GET request to the calendar endpoint suffixed by the calendar id. This request MUST include a mytoken with the read@manage_mytokens:notify capability as authorization.

Example

GET /api/v0/notifications/calendars/59ckwFkBdQoqo6t5jAkdnek24kd9HvUB HTTP/1.1
Host: mytoken.example.com
Authorization: Bearer eyJhbGcio...

Calendar Info Response¶

A successful response will redirect to the ics_path which will return the ICS data with content type text/calendar.

Update Calendar¶

Update Calendar Request¶

To update a calendar's description and/or tags, the client sends a PUT request to the calendar endpoint suffixed by the calendar id and adds the following parameters using the application/json format in the HTTP request entity-body:

Parameter	Necessity	Description
`mytoken`	REQUIRED	A mytoken used as authorization; MUST have the `manage_mytokens:notify` capability
`description`	OPTIONAL	The new description for the calendar
`tags`	OPTIONAL	A JSON Array of tag names to replace the current tags

At least one of description or tags must be provided.

Example

PUT /api/v0/notifications/calendars/59ckwFkBdQoqo6t5jAkdnek24kd9HvUB HTTP/1.1
Host: mytoken.example.com
Content-Type: application/json

{
    "mytoken": "eyJhbGcio...",
    "description": "Updated description for CI tokens",
    "tags": ["CI", "production", "critical"]
}

Update Calendar Response¶

A successful response returns the updated calendar object with HTTP status code 200.

Add Token to Calendar¶

Add Token Request¶

To add a mytoken to a calendar, the client sends a POST request to the calendar endpoint suffixed by the calendar id and adds the following parameters using the application/json or application/x-www-form-urlencoded format in the HTTP request entity-body:

Parameter	Necessity	Description
`mytoken`	REQUIRED	A mytoken used as authorization; MUST have the `manage_mytokens:notify` capability
`mom_id`	REQUIRED	The mom id of the mytoken that should be added
`comment`	OPTIONAL	A comment that, if present, will be included in the expiration event's description

Example

POST /api/v0/notifications/calendars/59ckwFkBdQoqo6t5jAkdnek24kd9HvUB HTTP/1.1
Host: mytoken.example.com
Content-Type: application/json

{
    "mytoken": "eyJhbGcio...",
    "mom_id": "Kqi9Jvwz5v4QCpNGrx8oon5ZJmtQEZ+zK/s52ynWpUMkl4kjEMskeLL3RqTkhvC6FOk7mTs1tJPdLXPx8OZ+uQ=="
}

Add Token Response¶

A successful response has the HTTP status code 200 and returns the updated calendar object as described under Calendar List Response.

Example

HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": "59ckwFkBdQoqo6t5jAkdnek24kd9HvUB",
    "ics_path": "https://mytoken.example.com/calendars/59ckwFkBdQoqo6t5jAkdnek24kd9HvUB",
    "description": "CI/CD pipeline tokens",
    "subscribed_tokens": [
        "rB8g1NhHqRNQL8S38DkzQgMJ9Df7wVmnuX1dkSk3kAlsUQM6igudDWL3ZMYf4xm1AL8/pQdGAetBa/y5ktydrg==",
        "Kqi9Jvwz5v4QCpNGrx8oon5ZJmtQEZ+zK/s52ynWpUMkl4kjEMskeLL3RqTkhvC6FOk7mTs1tJPdLXPx8OZ+uQ=="
    ]
}

Add Tag to Calendar¶

Add Tag Request¶

To add a tag to a calendar, the client sends a POST request to the calendar endpoint suffixed by the calendar id and /tags, and adds the following parameters using the application/json format in the HTTP request entity-body:

Parameter	Necessity	Description
`mytoken`	REQUIRED	A mytoken used as authorization; MUST have the `manage_mytokens:notify` capability
`tag`	REQUIRED	The tag name to add to the calendar

Example

POST /api/v0/notifications/calendars/59ckwFkBdQoqo6t5jAkdnek24kd9HvUB/tags HTTP/1.1
Host: mytoken.example.com
Content-Type: application/json

{
    "mytoken": "eyJhbGcio...",
    "tag": "critical"
}

Add Tag Response¶

A successful response has the HTTP status code 204 and no content, unless the used mytoken has been rotated, in this case the updated mytoken is returned with a status code of 200.

Remove Tag from Calendar¶

Remove Tag Request¶

To remove a tag from a calendar, the client sends a DELETE request to the calendar endpoint suffixed by the calendar id and /tags, and adds the following parameters using the application/json format in the HTTP request entity-body:

Parameter	Necessity	Description
`mytoken`	REQUIRED	A mytoken used as authorization; MUST have the `manage_mytokens:notify` capability
`tag`	REQUIRED	The tag name to remove from the calendar

Example

DELETE /api/v0/notifications/calendars/59ckwFkBdQoqo6t5jAkdnek24kd9HvUB/tags HTTP/1.1
Host: mytoken.example.com
Content-Type: application/json

{
    "mytoken": "eyJhbGcio...",
    "tag": "obsolete-tag"
}

Remove Tag Response¶

A successful response has the HTTP status code 204 and no content, unless the used mytoken has been rotated, in this case the updated mytoken is returned with a status code of 200.

Delete Calendar¶

Delete Calendar Request¶

To delete a calendar, the client sends a DELETE request to the calendar endpoint suffixed by the calendar id. The request MUST include a mytoken with the manage_mytokens:notify capability as authorization.

Example

DELETE /api/v0/notifications/calendars/59ckwFkBdQoqo6t5jAkdnek24kd9HvUB HTTP/1.1
Host: mytoken.example.com
Authorization: Bearer eyJhbGcio...

Delete Calendar Response¶

A successful response has the HTTP status code 204 and no content, unless the used mytoken has been rotated, in this case the updated mytoken is returned with a status code of 200.

Last update: March 30, 2026 14:00:08