Service applications

Service applications are used to manage user resources in an organization via the API. For example, you can use them to back up your emails or manage events in Yandex Calendar. You can create up to 20 service applications.

Service applications are available for Optimal and Advanced service plans. If you disable the plan, you won't be able to manage service applications. You can clear the list of applications within a month. After one month, the applications will be removed from the organization.

Alert

Under clause 3.7 of the offer, after enabling access, the admin is obliged to notify all users and, if necessary, obtain their written consent (unless it was obtained earlier).

Connect service applications

  1. Log in to the account of the company owner.

  2. Register an application that will manage the list of service applications in the organization.

    1. Open the Create an OAuth app page.

    2. Enter the name of your service and attach an icon if necessary.

    3. In the Platforms block, select Web services. In the Redirect URI field, click Enter URL for debugging.

    4. In the Data access section, specify the access rights that are required to manage service applications in the organization:

      • ya360_security:service_applications_read: To read the list of service applications.

      • ya360_security:service_applications_write: To manage the list of service applications (read and write).

    5. Add your contact email. Click Create app at the bottom of the page. Its description will appear on the screen.

    6. Copy the application ID from the ClientID field. You'll need it to get an OAuth token. In the future, the page with all your applications will be available at oauth.yandex.com.

  3. Request an OAuth token in any way convenient to you. You'll need it later to register all service applications in the organization.

    You can get a debug OAuth token manually:

    1. Follow the link

      https://oauth.yandex.ru/authorize?response_type=token&client_id=<main_app_client_id>

      Replace <main_app_client_id> with ClientID from Step 2.6.

    2. If the OAuth token is issued to your application for the first time, an authorization screen will open. After logging in, Yandex OAuth will redirect you to the page with the token. Learn more about debug tokens.

  4. Notify users and obtain their consent (unless it was obtained earlier) to the admin's access to their resources in accordance with clause 3.7 of the offer.

  5. Activate the service applications function using the following request:

    POST https://api360.yandex.net/security/v1/org/<org_id>/service_applications/activate

    Replace <org_id> with the ID of your organization.

  6. Register the service application. You can use it to get temporary OAuth tokens. A temporary token is valid for 1 hour.

    1. Create a separate OAuth application in the same way you created the main application (Step 2). Specify the access rights for this application that will be used in API requests.

    2. Make the application from the previous step the service application for the organization.

      Example
      curl --location \
--request POST 'https://api360.yandex.net/security/v1/org/<org_id>/service_applications' \
--header 'Authorization: OAuth <owner_token_to_manage_service_app>’ \
--header 'Content-Type: application/json' \
--data-raw '{ \
  "applications": [ \
    { \
      "id": “<OAuth_service_app_client_id>”, \
      "scopes": [ \
        "cloud_api:disk.app_folder", \
        "cloud_api:disk.read", \
        "cloud_api:disk.write", \
        "cloud_api:disk.info" \
      ] \
    } \
  ] \
}'

      Substitute the following values into the code:

      • <org_id>: ID of your organization.

      • <owner_token_to_manage_service_app>: OAuth token from Step 3.

      • <OAuth_service_app_client_id>: ClientID of the service application from Step 6.1.

    3. Check that the application was added as a service application.

      Example
      curl --location  \
--request GET 'https://api360.yandex.net/security/v1/org/<org_id>/service_applications'  \
--header 'Authorization: OAuth <owner_token_to_manage_service_app>'

    To connect other service applications, repeat Step 6.

  7. Get a temporary user token. You can do this using the following API request:

    POST /token HTTP/1.1
   Host: http://oauth.yandex.ru
   Content-type: application/x-www-form-urlencoded
    Example
    curl --location \
--request POST 'https://oauth.yandex.ru/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=urn:ietf:params:oauth:grant-type:token-exchange' \
--data-urlencode 'client_id=<OAuth_service_app_client_id>' \
--data-urlencode 'client_secret=<OAuth_service_app_client_secret>' \
--data-urlencode 'subject_token=<user_id>' \
--data-urlencode 'subject_token_type=urn:yandex:params:oauth:token-type:uid'

    or

    curl --location
--request POST 'https://oauth.yandex.ru/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=urn:ietf:params:oauth:grant-type:token-exchange' \
--data-urlencode 'client_id=<OAuth_service_app_client_id>' \
--data-urlencode 'client_secret=<OAuth_service_app_client_secret>' \
--data-urlencode 'subject_token=<user_email>' \
--data-urlencode 'subject_token_type=urn:yandex:params:oauth:token-type:email'

    Substitute the following values into the code:

    • <OAuth_service_app_client_id>: ClientID of the service application from Step 6.1.

    • <OAuth_service_app_client_secret>: Client secret of the service application.

    • <user_id>: ID of the user for whom you're obtaining a token.

    • <user_email>: The email address of the user (formatted as username@domain.ru) for whom you're obtaining a token.

    The response will contain a token that the user must use in their requests to Yandex 360 API services.

Service application management is described in detail in API 360 Help.

Examples of requests for managing user resources

Temporary tokens issued by service applications provide API access to some user resources in the organization, for example, to back up data or search for information.

Yandex Disk

The Yandex Disk API is intended for working with files and managing access to them. You can send requests to the Yandex Disk API using Polygon.

Example

Request for meta-information about the employee's Yandex Disk:

curl --request GET 'https://cloud-api.yandex.net/v1/disk' \
--header 'Accept: application/json' \
--header 'Authorization: OAuth <oauth_token>'

Replace <oauth_token> with the value of the temporary user token from Step 7.

Learn more about working with the Yandex Disk REST API.

Yandex Mail

Applications can access Yandex Mail mailboxes via the OAuth protocol. OAuth authorization is supported by IMAP and SMTP Yandex Mail servers.

Example

Python script for counting user emails using the IMAP protocol:

import imaplib

def generate_oauth2_string(username, access_token):
    auth_string = 'user=%s\1auth=Bearer %s\1\1' % (username, access_token)
    return auth_string

def get_imap_connector(username="<user_email>", token="<oauth_token>"):
    auth_string = generate_oauth2_string(username, token)
    imap_connector = imaplib.IMAP4_SSL("imap.yandex.com", 993)
    imap_connector.authenticate('XOAUTH2', lambda x: auth_string)
    return imap_connector

def get_total_emails(imap_connector):
    mailboxes = []
    ttl_emails = 0
    for mailbox in imap_connector.list()[1]:
        mailboxes.append(mailbox.decode("utf-8").split()[-1].replace('"', ''))
        for mailbox in mailboxes:
            try:
                imap_connector.select(mailbox)
                resp_code, mail_count = imap_connector.select(mailbox=mailbox, readonly=True)
                ttl_emails += int(mail_count[0].decode("utf-8"))
            except imaplib.IMAP4.error:
                print(f"Folder: {folder} Error reading emails")
            except ValueError:
                print(f"Folder: {folder} Error reading emails")
    user_logout(imap_connector)
    return ttl_emails

get_total_emails(get_imap_connector())

Substitute the following values into the code:

  • <user_email>: The email address of the user (formatted as username@domain.ru) for whom you're obtaining data.
  • <oauth_token>: The temporary user token from Step 7.

For more information about how mail protocols work, see the IMAP description and SMTP specifications.

Yandex Calendar

OAuth tokens can be used to interact with Yandex Calendar via the CalDAV protocol.

Example 1

Python script to delete the user's Yandex Calendar:

import caldav

def get_principal(username, leg_token):
    client = caldav.DAVClient(url="https://caldav.yandex.ru/", username=username, password=leg_token)
    principal = client.principal()
    return principal

my_principal = get_principal("<user_email>", "<oauth_token>")

def find_delete_calendar(my_principal, calendar_name="My calendar"):
    try:
        calendar = my_principal.calendar(name=calendar_name)
        assert calendar
        print(f"We found an existing calendar with name {calendar_name}, now deleting it")
        calendar.delete()
    except caldav.error.NotFoundError:
        print("Calendar was not found")

find_delete_calendar(my_principal)

Substitute the following values into the code:

  • <user_email>: The email address of the user (formatted as username@domain.ru) for whom you're obtaining data.

  • <oauth_token>: The temporary user token from Step 7.

Note

If the admin deletes the user's calendar, neither the admin nor the user will be able to restore it in the future.

Example 2

Requests to create a meeting in Yandex Calendar with a link to a video meeting in Yandex Telemost:

  • A conference for a one-time event.

    curl -v "https://caldav.yandex.ru/calendars/<user_email>/events-default/<event_uid>.ics" \
-H "Authorization: OAuth <oauth_token>" \
-H "Content-type: text/ics" \
-X PUT \
--data-binary "
  BEGIN:VCALENDAR
  BEGIN:VEVENT
  X-TELEMOST-REQUIRED:TRUE
  DESCRIPTION:Single event
  UID:<event_uid>
  DTSTART:20230417T120000Z
  END:VEVENT
  END:VCALENDAR"

    Substitute the following values into the code:

    • <user_email>: The email address of the user (formatted as username@domain.ru) for whom you're obtaining data.
    • <event_uid>: The ID of the meeting and file name (for example, a5e3e7b0-dd11-11ed).
    • <oauth_token>: The temporary user token from Step 7.

    Example of a successful response:

    HTTP/1.1 201 Created

    curl -v "https://caldav.yandex.ru/calendars/<user_email>/events-default/<event_uid>.ics" \
  -H "Authorization: OAuth <oauth_token>"

    Substitute the following values into the code:

    • <user_email>: The email address of the user (formatted as username@domain.ru) for whom you're obtaining data.

    • <event_uid>: The ID of the meeting and file name (for example, a5e3e7b0-dd11-11ed).

    • <oauth_token>: The temporary user token from Step 7.

    Example of a successful response:

    HTTP/1.1 200 OK
BEGIN:VCALENDAR
...
BEGIN:VEVENT
DTSTART:20230417T120000Z
DTEND:20230417T120000Z
SUMMARY:No name
UID:a5e3e7b0-dd11-11ed
DESCRIPTION:Link to video conference: https://telemost.yandex.ru/j/78566269088286\n\nSingle event
X-TELEMOST-CONFERENCE:https://telemost.yandex.ru/j/78566269088286
...
END:VEVENT
END:VCALENDAR

  • A conference for a recurring event.

    curl -v "https://caldav.yandex.ru/calendars/<user_email>/events-default/<event_uid>.ics" \
-H "Authorization: OAuth <oauth_token>" \
-H "Content-type: text/ics" \
-X PUT \
--data-binary "
  BEGIN:VCALENDAR
  BEGIN:VEVENT
  X-TELEMOST-REQUIRED:TRUE
  DESCRIPTION:Weekly event
  UID:<event_uid>
  DTSTART:20230411T200000Z
  RRULE:FREQ=WEEKLY
  END:VEVENT
  END:VCALENDAR"

    Substitute the following values into the code:

    • <user_email>: The email address of the user (formatted as username@domain.ru) for whom you're obtaining data.

    • <event_uid>: The ID of the meeting and file name (for example, a5e3e7b0-dd11-11ed).

    • <oauth_token>: The temporary user token from Step 7.

    Example of a successful response:

    HTTP/1.1 201 Created

    curl -v "https://caldav.yandex.ru/calendars/<user_email>/events-default/<event_uid>.ics" \
  -H "Authorization: OAuth <oauth_token>"

    Substitute the following values into the code:

    • <user_email>: The email address of the user (formatted as username@domain.ru) for whom you're obtaining data.

    • <event_uid>: The ID of the meeting and file name (for example, a5e3e7b0-dd11-11ed).

    • <oauth_token>: The temporary user token from Step 7.

    Example of a successful response:

    BEGIN:VCALENDAR
...
BEGIN:VEVENT
RECURRENCE-ID:20230411T200000Z
X-TELEMOST-CONFERENCE:https://telemost.yandex.ru/j/39864310386563
DESCRIPTION:Link to video conference: https://telemost.yandex.ru/j/39864310386563\n\nWeekly event
...
END:VEVENT
BEGIN:VEVENT
RRULE:FREQ=WEEKLY;BYDAY=TU;INTERVAL=1
DESCRIPTION:Link to video conference: https://telemost.yandex.ru/j/39864310386563\n\nWeekly event
...
END:VEVENT

When sending the PUT request to create or change an event in the calendar, the client adds the non-standard property X-TELEMOST-REQUIRED to VEVENT components. When the server receives the request, it generates a link to the video conference in Yandex Telemost and adds it to the meeting description.

When the client reads the conference, the server doesn't specify the X-TELEMOST-REQUIRED property. But if the link to the video meeting in Yandex Telemost was generated, it returns this link in the X-TELEMOST-CONFERENCE non-standard property.

For more information about working with the CalDAV protocol, see the specifications.

Contact support

Special code allowing access to data on behalf of a specific user.

A protocol for synchronizing calendar and address book data between the mail server and the client.

Previous
Outgoing mail protection from leaks
Next
API scenarios