# API Scope

### **Definition**

API Scope is a configuration for defining the range of permissions or access levels that users or applications have when using APIs. Often integrated with OAuth 2.0, it restricts client access to specific resources or functions.

### **Advantages**

* **Fine-grained Control:** Restricts users to specific resources or operations.
* **Enhanced Security:** Reduces the risk of unauthorized users operating on sensitive data or functions.
* **Simplified Authorization Logic:** Manages authorization needs using labels, reducing code complexity.

### **Use Cases**

* **Restricting Functions:**\
  Example: A "read-only" scope allows clients to only read resources, while a "read-write" scope allows modifications.
* **Resource-based Authorization:**\
  Example: A client may access `/user/profile` but not `/user/settings`.
* **Dynamic Authorization:**\
  Allows API authorization to be determined dynamically based on Scope, suitable for scenarios requiring temporary expansion or reduction of permissions.

### **Standard Operating Process**

1. **Design the Scope Structure:**
   * Design Scope labels based on resources and operations, such as `read`, `write`, `admin`.
   * Map Scope labels to API functions (e.g., `/users` resource mapped to `read-users`, `write-users`).
2. **Define Scope Rules:**
   * Specify which Scopes correspond to which API operations.
   * Establish inheritance or hierarchy logic for Scopes (e.g., `admin` includes `read` and `write` permissions).
3. **Authorize and Verify:**
   * Issue Tokens containing Scopes when a client requests access.
   * Validate the requested Scope through the API Gateway or backend.
4. **Runtime Control:**
   * When APIs are invoked, check if the request Token contains the matching Scope.
   * Execute requests or return a rejection response based on the Scope configuration.


---

# Agent Instructions: 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:

```
GET https://docs.tpi.dev/overview/key-concepts/api-scope.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.