🔒Auth

Connect an Outlook Account

Get OAuth URL

There are 2 steps for connecting a Microsoft Outlook account. The first step is to request a Microsoft OAuth URL.

Get an OAuth URL

GET https://api.pyas.io/microsoft/oauth

Get a Microsoft OAuth URL

Query Parameters

Name	Type	Description
email*	String	a user's email address
state	String	optional application state

Headers

Name	Type	Description
x-api-key*	String	API key

200: OK OAuth URL was generated successfully

{
    "success": true,
    "url": "https://login.microsoftonline.com/common/oauth2/v2.0/authorize?client_id=..."
}

400: Bad Request no email address param was provided

{
    "errors": [
        {
            "msg": "Invalid value",
            "param": "email",
            "location": "query"
        },
        {
            "msg": "a valid email is required.",
            "param": "email",
            "location": "query"
        }
    ]
}

400: Bad Request Invalid email address provided

{
    "errors": [
        {
            "value": "bademail",
            "msg": "a valid email is required.",
            "param": "email",
            "location": "query"
        }
    ]
}

401: Unauthorized Invalid or no api key provided

{
    "error": "Unauthorized. Invalid API key."
}

Connect Account

The next step is to connect the account. After you get an OAuth URL, you should direct your user to that URL in the browser. The user will then have to authorized/allow access on the OAuth screen. Once the user allows access, Microsoft will redirect the user back to whatever redirect URL that you've set in Pyas. The URL will contain a code parameter, which you will need to use in the connect request.

Connect Account

POST https://api.pyas.io/microsoft/connect

Connect Microsoft Account

Headers

Name	Type	Description
x-api-key*	String	API key

Request Body

Name	Type	Description
code*	String	code returned from Microsoft OAuth
name*	String	user's full name

200: OK Account connected successfully

{
    "success": true,
    "data": {
        "account": {
            "accountId": "03fdd65-d25f-4f00-94e3-9c23ea99738-56321c14",
            "email": "[e-mail]",
            "name": "Jon Snow",
            "provider": "microsoft",
            "status": "active",
            "scopes": [
                "openid",
                "offline_access",
                "profile",
                "https://graph.microsoft.com/User.Read",
                "https://graph.microsoft.com/Calendars.Read",
                "https://graph.microsoft.com/Calendars.Read.Shared",
                "https://graph.microsoft.com/Calendars.ReadWrite",
                "https://graph.microsoft.com/Calendars.ReadWrite.Shared",
            ]
        }
    }
}

400: Bad Request invalid code

{
    "success": false,
    "error": "invalid_grant",
    "code": 400
}

400: Bad Request no code provided

{
    "errors": [
        {
            "msg": "a code is required.",
            "param": "code",
            "location": "body"
        },
        {
            "msg": "code must be a string.",
            "param": "code",
            "location": "body"
        }
    ]
}

Note: Be sure to save the accountId returned from the successful connect request. You will need it in order to access the user's Outlook calendar.