# Authentication & Swagger

## Intro

The full list of API functions with descriptions and JSON schema can be found here: <https://safcregistry.energyweb.org/api/swagger#/>

This list includes functions for internal use only and will throw a 403 error if you attempt to call them.

Warning - only attempt to use the POST, PATCH, and DELETE functions if you completely understand how they work. These functions can cause irreversible changes to your company's presence on the registry, your accounts, users from your company, and your SAF Certificates

## Authentication

### Current Authentication (Supported until at least 06/30/2026)

You'll need to provide your auth token each time you make a request to the SAFc Registry and you'll need to include it in the header. Example Python code with the auth token "abcd123456789":

```
import requests

auth_header = { 'Authorization': 'Bearer abcd123456789'}

my_info = 'https://safcregistry.energyweb.org/api/users/me'

r = requests.get(my_info, header=auth_header)
```

### New Authorization Flow (From 05/20/2026)

The new authorization flow is as follows:

1. Generate an **Access Token** through the registry's Profile Settings screen.
2. Exchange this Access Token for a temporary **Auth Token** (valid for 30 minutes) using the new exchange endpoint:

```
POST /api/auth/exchange
Content-Type: application/json
{ "token": "<accessToken>" }
```

3. The exchange endpoint returns an Auth Token (another JWT token **valid for 30 minutes**) that is used for subsequent requests.
4. Pass the Auth Token in the Authorization header for all subsequent SAFc API requests: **Authorization: Bearer\<authTokenFromExchangeEndpoint>**

## Noteworthy functions

| Function                                                                                                                                                                                                                                 | Purpose                                                     | Inputs                        | Outputs                                                                |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- | ----------------------------- | ---------------------------------------------------------------------- |
| [GET](https://safcregistry.energyweb.org/api/swagger#/user/UserController_getMyUserData)[/api/users/me](https://safcregistry.energyweb.org/api/swagger#/user/UserController_getMyUserData)                                               | Gets information about the API user                         | None                          | User's: ID, email, name, companies, accounts, account memberships      |
| [GET/api/unit](https://safcregistry.energyweb.org/api/swagger#/unit/UnitController_getUnits)                                                                                                                                             | Provide list of all SAF certificates for a specific account | Account ID                    | Large JSON with all certificates in an account and all of their fields |
| [GET](https://safcregistry.energyweb.org/api/swagger#/unit/UnitController_getUnitById)[/api/unit/{id}](https://safcregistry.energyweb.org/api/swagger#/unit/UnitController_getUnitById)                                                  | Get information about a specific certificate                | Certificate ID                | Information about specific certificate                                 |
| [GET](https://safcregistry.energyweb.org/api/swagger#/unit-process/UnitProcessController_getUnitProcesses)[/api/unit-process/query](https://safcregistry.energyweb.org/api/swagger#/unit-process/UnitProcessController_getUnitProcesses) | Get a list of pending actions for a specific account        | Account ID, Pending\|Finished | Detailed list of actions for an account                                |


---

# 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.safcregistry.org/user-guide/api-documentation/authentication-and-swagger.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.