> For the complete documentation index, see [llms.txt](https://developers-apps-in-toss.toss.im/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers-apps-in-toss.toss.im/documentation/api-and-sdk-en/sdk/domains-api/permissions.md).

# Permissions

Provides functions to query and request device permissions (clipboard, contacts, album, camera, microphone, location) and permission error classes.

### API List

| API                                                                                                         | Description                                  |
| ----------------------------------------------------------------------------------------------------------- | -------------------------------------------- |
| [`getPermission`](/documentation/api-and-sdk-en/sdk/domains-api/permissions/getpermission.md)               | Checks the current status of a permission    |
| [`requestPermission`](/documentation/api-and-sdk-en/sdk/domains-api/permissions/requestpermission.md)       | Requests a permission and returns the result |
| [`openPermissionDialog`](/documentation/api-and-sdk-en/sdk/domains-api/permissions/openpermissiondialog.md) | Opens the permission settings dialog         |

Seven permission error classes (`OpenCameraPermissionError` and more are also provided — when a permission-required API is denied, instances of these classes are thrown.

### withPermission

#### Feature description

Wraps a function that requires permission. When you call the wrapped function, it first requests that permission, and if denied, `errorClass`it throws the error passed to errorClass, and if allowed, it executes the original function.

The returned function also has `getPermission()`to query the same permission, and `openPermissionDialog()`attached as static methods. Inside the framework, `Clipboard.getText`, `Device.getPhotos` the same API is built with this function, so `Clipboard.getText.getPermission()` you can check permissions in this form.

#### Type

**Params**

```ts
function withPermission<T extends (...args: any[]) => any>(
  fn: T, // Function to run after permission is allowed
  name: PermissionName, // Name of the permission to request
  access: PermissionAccess, // Type of access to request
  errorClass: new () => PermissionErrorType, // Error class to throw if permission is denied
): PermissionFunctionWithDialog<T>;
```

**Response**

```ts
type PermissionFunctionWithDialog<T extends (...args: any[]) => any> = T & {
  getPermission: GetPermissionFunction;
  openPermissionDialog: PermissionDialogFunction;
};
```

#### Error

| Code                            | Description                                           |
| ------------------------------- | ----------------------------------------------------- |
| `errorClass`The error passed to | when the permission request result is `denied`denied. |

#### Example code

```js
import {
  withPermission,
  OpenCameraPermissionError,
} from "@apps-in-toss/web-framework";

const captureWithCamera = withPermission(
  () => {
    // Logic to run after camera permission is allowed
  },
  "camera",
  "access",
  OpenCameraPermissionError,
);

try {
  await captureWithCamera();
} catch (error) {
  if (error instanceof OpenCameraPermissionError) {
    // You can open the permission dialog and request it again.
    const status = await captureWithCamera.openPermissionDialog();
    console.log(status); // 'allowed' | 'denied'
    return;
  }
  console.error(error);
}
```

### PermissionError

#### Feature description

This is the common parent class of permission errors. When handling multiple permission errors at once, `error instanceof PermissionError`You can check it with `name`is `` `${methodName} permission error` `` format.

#### Type

**Params**

```ts
interface PermissionErrorConstructorParams {
  methodName: PermissionFunctionName;
  message: string;
}
```

**Response**

```ts
class PermissionError extends Error {
  name: string; // `${methodName} permission error`
  message: string;
}
```

#### Example code

```js
import { Clipboard, PermissionError } from "@apps-in-toss/web-framework";

try {
  const text = await Clipboard.getText();
  console.log(text);
} catch (error) {
  if (error instanceof PermissionError) {
    console.warn("Permission denied:", error.message);
    return;
  }
  console.error(error);
}
```

### GetClipboardTextPermissionError

#### Feature description

This error occurs when clipboard read permission is denied. `error instanceof GetClipboardTextPermissionError`You can check it with `PermissionError`extends it.

#### Type

```ts
class GetClipboardTextPermissionError extends PermissionError {
  name: "getClipboardText permission error";
  message: "Clipboard read permission was denied.";
}
```

#### Example code

```js
import {
  Clipboard,
  GetClipboardTextPermissionError,
} from "@apps-in-toss/web-framework";

try {
  const text = await Clipboard.getText();
  console.log(text);
} catch (error) {
  if (error instanceof GetClipboardTextPermissionError) {
    console.warn("You don't have clipboard read permission.");
  }
}
```

### SetClipboardTextPermissionError

#### Feature description

This error occurs when clipboard write permission is denied. `error instanceof SetClipboardTextPermissionError`You can check it with `PermissionError`extends it.

#### Type

```ts
class SetClipboardTextPermissionError extends PermissionError {
  name: "setClipboardText permission error";
  message: "Clipboard write permission was denied.";
}
```

#### Example code

```js
import {
  Clipboard,
  SetClipboardTextPermissionError,
} from "@apps-in-toss/web-framework";

try {
  await Clipboard.setText("Text to copy");
} catch (error) {
  if (error instanceof SetClipboardTextPermissionError) {
    console.warn("You don't have clipboard write permission.");
  }
}
```

### FetchContactsPermissionError

#### Feature description

This error occurs when contacts permission is denied. `error instanceof FetchContactsPermissionError`You can check it with `PermissionError`extends it.

#### Type

```ts
class FetchContactsPermissionError extends PermissionError {
  name: "fetchContacts permission error";
  message: "Contacts permission was denied.";
}
```

#### Example code

```js
import {
  Device,
  FetchContactsPermissionError,
} from "@apps-in-toss/web-framework";

try {
  const contacts = await Device.getContacts({ size: 10, offset: 0 });
  console.log(contacts);
} catch (error) {
  if (error instanceof FetchContactsPermissionError) {
    console.warn("You don't have contacts permission.");
  }
}
```

### FetchAlbumPhotosPermissionError

#### Feature description

This error occurs when album permission is denied. `error instanceof FetchAlbumPhotosPermissionError`You can check it with `PermissionError`extends it.

#### Type

```ts
class FetchAlbumPhotosPermissionError extends PermissionError {
  name: "fetchAlbumPhotos permission error";
  message: "Album permission was denied.";
}
```

#### Example code

```js
import {
  Device,
  FetchAlbumPhotosPermissionError,
} from "@apps-in-toss/web-framework";

try {
  const photos = await Device.getPhotos();
  console.log(photos);
} catch (error) {
  if (error instanceof FetchAlbumPhotosPermissionError) {
    console.warn("You don't have album permission.");
  }
}
```

### GetCurrentLocationPermissionError

#### Feature description

This error occurs when location permission is denied. `error instanceof GetCurrentLocationPermissionError`You can check it with `PermissionError`extends it.

#### Type

```ts
class GetCurrentLocationPermissionError extends PermissionError {
  name: "getCurrentLocation permission error";
  message: "Location permission was denied.";
}
```

#### Example code

```js
import {
  Accuracy,
  Device,
  GetCurrentLocationPermissionError,
} from "@apps-in-toss/web-framework";

try {
  const location = await Device.getLocation({ accuracy: Accuracy.Balanced });
  console.log(location);
} catch (error) {
  if (error instanceof GetCurrentLocationPermissionError) {
    console.warn("No location permission.");
  }
}
```

### StartUpdateLocationPermissionError

#### Feature description

This error occurs when location update permission is denied. `GetCurrentLocationPermissionError`because it is an alias referring to the same class as `error instanceof StartUpdateLocationPermissionError`is `GetCurrentLocationPermissionError` also in the instance `true`.

#### Type

```ts
const StartUpdateLocationPermissionError = GetCurrentLocationPermissionError;
```

#### Example code

```js
import {
  Accuracy,
  Device,
  StartUpdateLocationPermissionError,
} from "@apps-in-toss/web-framework";

const cleanup = Device.subscribeLocation({
  options: {
    accuracy: Accuracy.Balanced,
    timeInterval: 3000,
    distanceInterval: 10,
  },
  onEvent: (location) => {
    console.log(location);
  },
  onError: (error) => {
    if (error instanceof StartUpdateLocationPermissionError) {
      console.warn("No location permission.");
    }
    cleanup();
  },
});
```

### OpenCameraPermissionError

#### Feature description

This error occurs when camera permission is denied. `error instanceof OpenCameraPermissionError`You can check it with `PermissionError`extends it.

#### Type

```ts
class OpenCameraPermissionError extends PermissionError {
  name: "openCamera permission error";
  message: "Camera permission was denied.";
}
```

#### Example code

```js
import { Device, OpenCameraPermissionError } from "@apps-in-toss/web-framework";

try {
  const image = await Device.openCamera();
  console.log(image);
} catch (error) {
  if (error instanceof OpenCameraPermissionError) {
    console.warn("You don't have camera permission.");
  }
}
```

### PermissionName

#### Feature description

This is the name type that identifies a permission.

#### Type

```ts
type PermissionName =
  | "clipboard" // clipboard
  | "contacts" // contacts
  | "photos" // album
  | "geolocation" // location
  | "camera" // camera
  | "microphone"; // microphone
```

### PermissionAccess

#### Feature description

This is the access-type for a permission. `read`/`write`is used for permissions where read/write are separated, such as clipboard, contacts, and album, `access`is used for permissions without separate access types, such as location, camera, and microphone.

#### Type

```ts
type PermissionAccess = "read" | "write" | "access";
```

### PermissionStatus

#### Feature description

This is the status type of a permission. `notDetermined`means the user has not yet responded to the permission request.

#### Type

```ts
type PermissionStatus = "notDetermined" | "denied" | "allowed";
```

### PermissionFunctionName

#### Feature description

This is the function-name type where permission errors occur. `PermissionError`of `name`Used when composing

#### Type

```ts
type PermissionFunctionName =
  | "getClipboardText"
  | "setClipboardText"
  | "fetchContacts"
  | "fetchAlbumPhotos"
  | "getCurrentLocation"
  | "openCamera";
```

### PermissionErrorConstructorParams

#### Feature description

`PermissionError` This is the parameter type passed to the constructor.

#### Type

```ts
interface PermissionErrorConstructorParams {
  methodName: PermissionFunctionName;
  message: string;
}
```

### PermissionErrorType

#### Feature description

`withPermission`of `errorClass` This is the shape of the error instance created by the parameters.

#### Type

```ts
interface PermissionErrorType extends Error {
  name: string;
  message: string;
}
```

### GetPermissionFunction

#### Feature description

`withPermission`Attached to a function wrapped with `getPermission` This is the signature of the static method.

#### Type

```ts
type GetPermissionFunction = () => Promise<PermissionStatus>;
```

### PermissionDialogFunction

#### Feature description

`withPermission`Attached to a function wrapped with `openPermissionDialog` This is the signature of the static method.

#### Type

```ts
type PermissionDialogFunction = () => Promise<
  Exclude<PermissionStatus, "notDetermined">
>;
```

### PermissionFunctionWithDialog

#### Feature description

`withPermission`This is the type of function returned by this. It adds `getPermission`/`openPermissionDialog` static methods to the original function signature.

#### Type

```ts
type PermissionFunctionWithDialog<T extends (...args: any[]) => any> = T & {
  getPermission: GetPermissionFunction;
  openPermissionDialog: PermissionDialogFunction;
};
```


---

# 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://developers-apps-in-toss.toss.im/documentation/api-and-sdk-en/sdk/domains-api/permissions.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.