> 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, albums, 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` etc.) are also provided — when an API that requires a permission is rejected, instances of these classes are thrown.

### withPermission

#### Feature description

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

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

#### Type

**Params**

```ts
function withPermission<T extends (...args: any[]) => any>(
  fn: T, // function to run after permission is allowed
  name: PermissionName, // permission name 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 | The permission request result is `denied`when the case is. |

#### 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 request again by opening the permission dialog.
    const status = await captureWithCamera.openPermissionDialog();
    console.log(status); // 'allowed' | 'denied'
    return;
  }
  console.error(error);
}
```

### PermissionError

#### Feature description

This is the common parent class for permission errors. When handling multiple permission errors at once, `error instanceof PermissionError`can be checked with this. `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 was denied:", error.message);
    return;
  }
  console.error(error);
}
```

### GetClipboardTextPermissionError

#### Feature description

An error that occurs when clipboard read permission is denied. `error instanceof GetClipboardTextPermissionError`can be checked with this. `PermissionError`inherits from

#### 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

An error that occurs when clipboard write permission is denied. `error instanceof SetClipboardTextPermissionError`can be checked with this. `PermissionError`inherits from

#### 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

An error that occurs when contacts permission is denied. `error instanceof FetchContactsPermissionError`can be checked with this. `PermissionError`inherits from

#### 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

An error that occurs when album permission is denied. `error instanceof FetchAlbumPhotosPermissionError`can be checked with this. `PermissionError`inherits from

#### 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

An error that occurs when location permission is denied. `error instanceof GetCurrentLocationPermissionError`can be checked with this. `PermissionError`inherits from

#### 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("You don't have location permission.");
  }
}
```

### StartUpdateLocationPermissionError

#### Feature description

An error that occurs when location update permission is denied. `GetCurrentLocationPermissionError`It is an alias referring to the same class as `error instanceof StartUpdateLocationPermissionError`is `GetCurrentLocationPermissionError` also on instances `true`It is.

#### 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("You don't have location permission.");
    }
    cleanup();
  },
});
```

### OpenCameraPermissionError

#### Feature description

An error that occurs when camera permission is denied. `error instanceof OpenCameraPermissionError`can be checked with this. `PermissionError`inherits from

#### 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("There is no camera permission.");
  }
}
```

### PermissionName

#### Feature description

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

The access type of a permission. `read`/`write`is used for permissions where read/write is distinguished, such as clipboard, contacts, and albums, `access`and is used for permissions without a distinction, such as location, camera, and microphone.

#### Type

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

### PermissionStatus

#### Feature description

The status type of a permission. `notDetermined`is the state where the user has not yet responded to the permission request.

#### Type

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

### PermissionFunctionName

#### Feature description

The name type of functions that raise permission errors. `PermissionError`the `name`Used when composing

#### Type

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

### PermissionErrorConstructorParams

#### Feature description

`PermissionError` The type of parameters passed to the constructor.

#### Type

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

### PermissionErrorType

#### Feature description

`withPermission`the `errorClass` 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` static method signature.

#### Type

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

### PermissionDialogFunction

#### Feature description

`withPermission`attached to a function wrapped with `openPermissionDialog` static method signature.

#### Type

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

### PermissionFunctionWithDialog

#### Feature description

`withPermission`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.