---
updatedAt: 2026-10-01T13:29:14.000Z
agentTools:
  projectIndex: https://developers.acuityscheduling.com/llms.txt
---

# OAuth2

**OAuth2 is recommended only if you're developing an application where many different users on Acuity need to authenticate. Just looking to authenticate with one account? Use [basic authentication](https://developers.acuityscheduling.com/docs/quick-start) instead.**

OAuth2 is a standard for applications to grant authorization and exchange credentials for an API securely. It's the best option for allowing users of your application to connect to Acuity.

A user clicks a connect button in the client (your application) and is redirected to Acuity to enter their credentials. After authorizing your app, the user is redirected back to your application with an authorization code which you'll exchange for an API access token.

You'll need to [register an Acuity OAuth2 client account](https://acuityscheduling.com/oauth2/register) to get started.

## Integration

Once you've got a [client account](https://acuityscheduling.com/oauth2/register), you'll be ready to start integrating. The first step is to redirect the user to our `authorization_url`. It's usually a good idea to display a button like "Connect to Acuity."

```text
https://acuityscheduling.com/oauth2/authorize?response_type=code&scope=api-v1&client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI&state=YOUR_CSRF_TOKEN
```

Include a `state` query parameter with a unique, unguessable value (for example a random string stored in the user's session). Acuity returns the same `state` value when redirecting back to your `redirect_uri`. Compare it to the value you sent to protect against CSRF on the callback.

```javascript
var Acuity = require('acuityscheduling');
var express = require('express');
var port = process.env.PORT || 8000;

var app = express();

app.get('/', function (req, res) {
  var acuity = Acuity.oauth({
    clientId: 'YOUR_CLIENT_ID',
    clientSecret: 'YOUR_CLIENT_SECRET',
    redirectUri: 'YOUR_REDIRECT_URI'
  });
  acuity.authorizeRedirect(res, { scope: 'api-v1' });
});

app.listen(port, function () {
  console.log('Listening on %s', port);
}).on('error', function () {
  if (e) return console.error(e);
});
```

```php
<?php
require_once('vendor/autoload.php');

$acuity = new AcuitySchedulingOAuth(array(
  'clientId' => 'YOUR_CLIENT_ID',
  'clientSecret' => 'YOUR_CLIENT_SECRET',
  'redirectUri' => 'YOUR_REDIRECT_URI'
));

$acuity->authorizeRedirect(array('scope' => 'api-v1'));
```

We'll verify your `client_id`, `redirect_uri` and `scope`, then display a login screen to the user allowing them to grant your application access to their Acuity account. Once the user is connected, Acuity will send them back to your `redirect_uri` with an `authorization_code`and your `state` value (if you provided one).

```text
http://example.org/oauth2?code=AN_AUTHORIZATION_CODE&state=YOUR_CSRF_TOKEN
```

Before exchanging the code for a token, confirm that `state` matches the value you generated when starting the authorize request.

Your application then exchanges the `authorization_code` for an `access_token` allowing access to the Acuity API for that user's account. Data should be sent to our token endpoint as an `application/x-www-form-urlencoded` POST request.

```shell
curl https://acuityscheduling.com/oauth2/token \
 -d grant_type=authorization_code \
 -d code=AN_AUTHORIZATION_CODE \
 -d redirect_uri=YOUR_REDIRECT_URI \
 -d client_id=YOUR_CLIENT_ID \
 -d client_secret=YOUR_CLIENT_SECRET
```

```javascript
var Acuity = require('acuityscheduling');
var express = require('express');
var url = require('url');
var port = process.env.PORT || 8000;

var app = express();

app.get(url.parse('YOUR_REDIRECT_URI').path, function (req, res) {
  var acuity = Acuity.oauth({
    clientId: 'YOUR_CLIENT_ID',
    clientSecret: 'YOUR_CLIENT_SECRET',
    redirectUri: 'YOUR_REDIRECT_URI'
  });
  acuity.requestAccessToken(req.query.code, function (err, tokenResponse) {
    if (err) return res.send(err);
    res.send(tokenResponse);
  });
});

app.listen(port, function () {
  console.log('Listening on %s', port);
}).on('error', function () {
  if (e) return console.error(e);
});
```

```php
<?php
require_once('vendor/autoload.php');

$acuity = new AcuitySchedulingOAuth(array(
  'clientId' => 'YOUR_CLIENT_ID',
  'clientSecret' => 'YOUR_CLIENT_SECRET',
  'redirectUri' => 'YOUR_REDIRECT_URI'
));

$tokenResponse = $acuity->requestAccessToken($_GET['code']);
print_r($tokenResponse);
```

If everything checks out, we'll respond with JSON and an `access_token`. If not, we'll do our best to tell you why.

**Response:**

```json
{
  "access_token": "AN_ACCESS_TOKEN",
  "token_type": "Bearer"
}
```

**Error:**

```json
{
  "error": "invalid_request",
  "message":"The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed. Check the \"code\" parameter."
}
```

Setting the `Authorization` header to `Bearer AN_ACCESS_TOKEN` will authenticate the user's account with our API server.

```shell
curl "https://acuityscheduling.com/api/v1/me" \
	-H "Authorization: Bearer AN_ACCESS_TOKEN"
```

```javascript
var Acuity = require('acuityscheduling');

var acuity = Acuity.oauth({
  accessToken: 'AN_ACCESS_TOKEN'
});

acuity.request('me', function (err, res, me) {
  if (err) return console.error(err);
  console.log(me);
});
```

```php
<?php
require_once('vendor/autoload.php');

$acuity = new AcuitySchedulingOAuth(array(
  'accessToken' => 'AN_ACCESS_TOKEN'
));

$me = $acuity->request('me');
print_r($me);
```

If you're done using a token, you can disable it using our disconnect endpoint:

```shell
curl https://acuityscheduling.com/oauth2/disconnect \
 -d access_token=AN_ACCESS_TOKEN \
 -d client_id=YOUR_CLIENT_ID \
 -d client_secret=YOUR_CLIENT_SECRET
```

***

### About OAuth 2.0

You can learn more about OAuth 2.0 at the helpful [community website](http://oauth.net/). Or put on your reading specs and check out [the official specification](http://tools.ietf.org/html/rfc6749).