> For the complete documentation index, see [llms.txt](https://docs.pyas.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pyas.io/rest-api-reference/google-calendar/auth.md).

# Auth

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

## Get OAuth URL

<mark style="color:blue;">`GET`</mark> `https://api.pyas.io/google/oauth`

#### Query Parameters

| Name                                    | Type   | Description                |
| --------------------------------------- | ------ | -------------------------- |
| email<mark style="color:red;">\*</mark> | String | a user's email address     |
| state                                   | String | optional application state |

#### Headers

| Name                                        | Type   | Description |
| ------------------------------------------- | ------ | ----------- |
| x-api-key<mark style="color:red;">\*</mark> | String | API key     |

{% tabs %}
{% tab title="200: OK OAuth URL was generated successfully" %}

```json
{
    "success": true,
    "url": "https://accounts.google.com/o/oauth2/v2/auth?..."
}
```

{% endtab %}

{% tab title="400: Bad Request no email address param was provided" %}

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

{% endtab %}

{% tab title="400: Bad Request Invalid email address provided" %}

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

{% endtab %}

{% tab title="401: Unauthorized Invalid or no api key provided" %}

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

{% endtab %}
{% endtabs %}

## 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, Google will redirect the user back to whatever redirect URL that you've set in Pyas. The URL will contain a `code` parameter, which we will use in the connect request.

<figure><img src="/files/MTuqMYArV0FTxfwffDB7" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/ltTvcY4gXaGZ9KX9i5iC" alt=""><figcaption></figcaption></figure>

## Connect Account

<mark style="color:green;">`POST`</mark> `https://api.pyas.io/google/connect`

Connect Google Account

#### Headers

| Name                                        | Type   | Description |
| ------------------------------------------- | ------ | ----------- |
| x-api-key<mark style="color:red;">\*</mark> | String | API key     |

#### Request Body

| Name                                   | Type   | Description                     |
| -------------------------------------- | ------ | ------------------------------- |
| code<mark style="color:red;">\*</mark> | String | code returned from Google OAuth |
| name<mark style="color:red;">\*</mark> | String | user's full name                |

{% tabs %}
{% tab title="200: OK Account connected successfully" %}

```json
{
    "success": true,
    "data": {
        "account": {
            "accountId": "3a39a739-4269-4565-b6ed-97757b5ebffc-po08qu",
            "email": "some-user@gmail.com",
            "name": "John Doe",
            "provider": "google",
            "status": "active",
            "scopes": [
                "https://www.googleapis.com/auth/userinfo.email",
                "https://www.googleapis.com/auth/userinfo.profile",
                "openid",
                "https://www.googleapis.com/auth/calendar.events",
                "https://www.googleapis.com/auth/calendar.freebusy",
                "https://www.googleapis.com/auth/admin.directory.resource.calendar.readonly",
                "https://www.googleapis.com/auth/calendar.calendarlist.readonly",
                "https://www.googleapis.com/auth/calendar.calendars.readonly"
            ]
        }
    }
}
```

{% endtab %}

{% tab title="400: Bad Request invalid code" %}

```json
{
    "success": false,
    "error": "invalid_grant", //the code provided is invalid
    "code": 400
}
```

{% endtab %}

{% tab title="400: Bad Request no code provided" %}

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

{% endtab %}
{% endtabs %}

**Note:** Be sure to save the <mark style="color:blue;">`accountId`</mark> returned from the successful connect request. You will need it in order to access the user's Google calendar.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.pyas.io/rest-api-reference/google-calendar/auth.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.