# Individual Connect

Cronofy sits as an intermediary layer between your application and your users’ calendars. This means that your application is actually authorizing with Cronofy rather than directly with the calendar services. We handle the different calendar service authorization processes so you don’t have to.

In order to do this we utilize the same OAuth2 security protocol that Google use. The flow goes like this:
**Individual Connect authorization flow**

Sequence diagram of Individual Connect authorization in seven steps between your application, the user, Cronofy and the user's calendar service, ending with your application storing an access token for the user's calendar.

```mermaid
sequenceDiagram
  autonumber
  participant Your Application
  participant Cronofy
  actor User
  participant Calendar service

  Your Application->>Cronofy: Send user to authorization page with scope
  User->>Calendar service: Log in and approve access
  Calendar service->>Cronofy: Access granted
  Cronofy->>Your Application: Redirect user back with code
  Your Application->>Cronofy: Redeem code
  Cronofy-->>Your Application: access_token, refresh_token and sub
  Your Application->>Your Application: Store tokens
```

1. Your application sends the user to Cronofy's hosted authorization page, specifying the permissions it needs on their calendars as the `scope`.
2. The user logs in to their calendar service and approves access.
3. The calendar service grants Cronofy access to the user's calendars.
4. Cronofy redirects the user back to your application with a `code` on the query string.
5. Your application redeems the `code` with Cronofy.
6. Cronofy returns an `access_token`, a `refresh_token` and a `sub` value to your application.
7. Your application stores the tokens. It uses the `access_token` to access the user's calendar, and the `refresh_token` to get a new `access_token` when one expires.



Now to walk you through setting up this flow.

## Identifying Your Application
The first step is to identify your application to Cronofy. This will give you the `CLIENT_ID` and `CLIENT_SECRET` required by the process.

Login to the [Developer Dashboard](https://app.cronofy.com/jump/developer) and choose *Create application* at the foot of the page.

This will give you the `CLIENT_ID` and `CLIENT_SECRET` you need.

You’ll note that there is a warning that *This application is not verified*. We’ll explain this later on this guide but for the moment it’s just a warning and is not going to prevent you from getting up and running.

## Gaining Your User’s Approval
Now we’ve got the identifiers needed for the application we can now setup the redirect flow. The URL to send your users to is constructed as follows.

```
https://app.cronofy.com/oauth/authorize?response_type=code
  &client_id={CLIENT_ID}
  &redirect_uri={REDIRECT_URI}
  &scope={SCOPE}
  &state={STATE}
```

- `CLIENT_ID` is the one associated with your app created above

- `REDIRECT_URI` the URL we should redirect the user to once they’ve completed the authorization

- `SCOPE` is the space separated (%20 on a URL string) list of permissions you’re requesting. Full docs here: [Request Authorization Docs](https://docs.cronofy.com/api-reference/authorization/individual-connect/request-authorization/index.md)

- `STATE` this is returned, unaltered, on the query string when the user is redirected back to your app.

## Getting the Access Token
When the user is redirected back to your application the query string will contain a `code` parameter. This is a one time use code used to retrieve the `access_token` and `refresh_token` for the user.

If you’re using a library for managing the OAuth flow then it is likely that it will handle this step for you as we’ve followed a series of conventions for the various token management endpoints. For example

- [omniauth](https://github.com/intridea/omniauth) for ruby automatically retrieves the tokens as part of populating it’s credential hash.

- [DotNetOpenAuth](http://dotnetopenauth.net/) as the RequestUserAuthorization on the WebServerClient for retrieving the tokens

- [OAuth2 Client for PHP](https://github.com/thephpleague/oauth2-client) provides $provider->getAccessToken() for this purpose.

If you need to retrieve the code yourself, then the [Request Access Token docs](https://docs.cronofy.com/api-reference/authorization/individual-connect/request-token/index.md) will give you what you need.

## Using the Access Token
The final step is to use the `access_token` to interact with the user’s calendars.

It is passed in an `Authorization` header in all HTTP requests to the API.

```http
GET /v1/calendars HTTP/1.1
Host: {data_center_url}
Authorization: Bearer {ACCESS_TOKEN}
```

More information in the [Authorization section](https://docs.cronofy.com/api-reference/authorization/authentication/index.md) of our API docs.

## Verifying Your Application
Calendar data is sensitive data so we need to do what we can to ensure that we’re only passing `codes` back to your application.

We do this by only allowing verified applications to request authorization using pre-configured `redirect_url` values.

Once your app is ready for production then let us know the URL(s) you’ll be redirecting the users to after they’ve authorized by emailing [support@cronofy.com](mailto:support@cronofy.com) and we can get your application verified.

## Dealing With A Token Expiry
One more thing to consider is handling token expiry. You will need to deal with it some point as `access_tokens` are designed to expire periodically.

This is the purpose of the `refresh_token` return alongside the `access_token`. If you store that against your user record as well then you can use it to request a new `access_token` at any time.

Again OAuth2 libraries generally have support for this flow.



---
[Read in HTML](https://docs.cronofy.com/developers/temporal-grid/connectivity/individual-connect/)