> For the complete documentation index, see [llms.txt](https://docs.veza.com/4yItIzMvkpAvMVFAamTf/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.veza.com/4yItIzMvkpAvMVFAamTf/developers/api/oaa/python-sdk.md).

# OAA Python SDK

{% hint style="info" %}
`oaaclient` can be downloaded from [GitHub](https://github.com/Veza/oaaclient-py), or installed with `pip3 install oaaclient`.
{% endhint %}

The \`oaaclient\` package provides data models, methods and a command-line interface for using the [Open Authorization API](https://github.com/Veza). You can use it to populate OAA templates including as Application, IdP, and HRIS, pushing OAA data to Veza and even as a general Veza API client.

The `oaaclient` SDK includes the following components:

* `oaaclient.client`: Veza API communication (data provider management, payload push, etc.). Requires an API key for authentication.
* `oaaclient.templates`: Classes for modeling and generating an OAA payload.
* `oaaclient.utils`: Additional utility functions (icon encoding, etc.).

For example usage, please see [modules](/4yItIzMvkpAvMVFAamTf/developers/api/oaa/python-sdk/oaaclient-modules.md) and the [`samples`](/4yItIzMvkpAvMVFAamTf/developers/api/oaa/oaa-sample-apps.md) directory.

**Sample Workflow**

Create the Veza API connection and a new custom application:

```python
from oaaclient.client import OAAClient
from oaaclient.templates import CustomApplication, OAAPermission

# creates a connection class to communicate with Veza
veza_con = OAAClient(url=veza_url, token=veza_api_key)

# creates a new Custom Application model
custom_app = CustomApplication(name="Sample App", application_type="sample")
```

Once the `CustomApplication` class is instantiated, you can use the public methods to populate the new app with local users, groups, resources, and permissions metadata:

```python
# define a permission
custom_app.add_custom_permission("owner", [OAAPermission.DataRead, OAAPermission.DataWrite])
# create a local user
jsmith = custom_app.add_local_user(unique_id="jsmith", name="Jane Smith", identities=["jane@example.com"])
# create a resource
resource1 = custom_app.add_resource(name="Resource 1", resource_type="Thing")
# assign a user to a resource
jsmith.add_permission(permission="owner", resources=[resource1])
```

Once all identities, permissions and resources are added to the CustomApplication object, the client connection handles the final push to Veza:

```python
veza_con.push_application(provider, data_source_name, application_object=custom_app)
```

See the [GitHub quickstarts ](https://github.com/Veza/oaa-community/tree/main/quickstarts)directory for complete examples.

#### Handling Errors

The `OAAClient` class handles API connections to Veza. If there are errors connecting or the API returns errors `OAAClient` will raise an `OAAClientError` exception. If the payload doesn't conform to the template requirements the `OAAClientError.details` will contain a list of any issues encountered.

```python
    try:
        response = veza_con.push_application(provider_name=provider_name,
                                             data_source_name=data_source_name,
                                             application_object=custom_app,
                                            )
        if response.get("warnings"):
            print("Push succeeded with warnings:")
            for w in response["warnings"]:
                print(w)
    except OAAClientError as e:
        print(f"Error: {e.error}: {e.message} ({e.status_code})", file=sys.stderr)
        if hasattr(e, "details"):
            for d in e.details:
                print(d, file=sys.stderr)
```

#### Additional documentation

Since any given source application or service will have different methods for retrieving entities, authorization, and other required metadata, each OAA connector will be slightly different. You should consult the API documentation for your application when considering how you will source the information, and refer to existing Veza-supported OAA connectors for real-world examples.

Connector source code and `oaaclient` [modules](/4yItIzMvkpAvMVFAamTf/developers/api/oaa/python-sdk/oaaclient-modules.md) are thoroughly annotated, for reference when building your own integrations.

For additional information about developing a custom OAA integration, please see [Open Authorization API](/4yItIzMvkpAvMVFAamTf/developers/api/oaa.md) section of the User Guide.


---

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

```
GET https://docs.veza.com/4yItIzMvkpAvMVFAamTf/developers/api/oaa/python-sdk.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.