> ## Documentation Index
> Fetch the complete documentation index at: https://docs.petal.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Credentials

> Retrieve your authorization credentials to access the API

Before you can access our API, you will need at least two pieces of identifying information: your bearer token, and your Workspace (Organization) ID. For some APIs, you may also need your unique User ID. All of these can be accessed through the authorization endpoint, as described below.

Before you can use the endpoint, you will need some software that can use APIs, such as cURL or Python.

## Authorization endpoint

The API endpoint for authorization is `https://cite.petal.org/api/auth`. You will need to send a POST request to the endpoint, with the following parameters:

<ParamField path="email" type="string">
  The email you use to sign in on Petal
</ParamField>

<ParamField path="password" type="string">
  Your password
</ParamField>

The sample code below shows how to make this request. Remember to replace `your_email@example.com` and `your_password` with your actual login credentials.

<CodeGroup>
  ```bash cURL theme={null}
  curl --location --request POST 'https://cite.petal.org/api/auth' \
  --header 'Content-Type: application/json' \
  --data-raw '{"email":"your_email@example.com","password":"your_password"}'
  ```

  ```python Python theme={null}
  import requests
  import json

  url = "https://cite.petal.org/api/auth"

  payload = json.dumps({
    "email": "your_email@example.com",
    "password": "your_password"
  })
  headers = {
    'Content-Type': 'application/json'
  }

  response = requests.request("POST", url, headers=headers, data=payload)

  print(response.text)
  ```

  ```java JavaScript theme={null}
  var settings = {
    "url": "https://cite.petal.org/api/auth",
    "method": "POST",
    "timeout": 0,
    "headers": {
      "Content-Type": "application/json"
    },
    "data": JSON.stringify({
      "email": "your_email@example.com",
      "password": "your_password"
    }),
  };

  $.ajax(settings).done(function (response) {
    console.log(response);
  });
  ```
</CodeGroup>

If successful, this request should return a JSON object with all the information you need. In particular, you are looking for these fields:

<ResponseField name="access_token" type="string" required>
  A cryptic bearer token that identifies you. It will be needed for all other API access.
</ResponseField>

<ResponseField name="id" type="integer" required>
  Your unique User ID.
</ResponseField>

<ResponseField name="organization_ids" type="integer[]" required>
  A list of the unique IDs of all Workspaces (also called Organizations) of which you are part.
</ResponseField>

Since every Petal user can create or join a number of Workspaces (also called Organizations in our API), you will need to find the ID of the particular Workspace you wish to work with, if you are in more than one Workspace. You might be able to do this by examining your role in each Workspace in the parameter

<ResponseField name="organization_roles" type="string[]" required>
  A list of your roles in all your Workspaces. Follows the same order as the `organization_ids` parameter.
</ResponseField>

However, if it's still not clear which Workspace ID you need, you can follow the instructions in the next section to identify the correct Workspace.

## Specifying your Workspace (Organization) ID

To do this, you should make a GET request to the `https://cite.petal.org/api/user/<id>/organization/list` endpoint. You will need to provide the bearer token you have just obtained from the previous step, as well as your user ID. Replace the sample values with your own in the code example below to get started.

<CodeGroup>
  ```bash cURL theme={null}
  curl --location --request GET 'https://cite.petal.org/api/user/<id>/organization/list' \
  --header 'Authorization: Bearer <token>'
  ```

  ```python Python theme={null}
  import requests

  url = "https://cite.petal.org/api/user/<id>/organization/list"

  payload={}
  headers = {
    'Authorization': 'Bearer <token>'
  }

  response = requests.request("GET", url, headers=headers, data=payload)

  print(response.text)
  ```

  ```java JavaScript theme={null}
  var settings = {
    "url": "https://cite.petal.org/api/user/<id>/organization/list",
    "method": "GET",
    "timeout": 0,
    "headers": {
      "Authorization": "Bearer <token>"
    },
  };

  $.ajax(settings).done(function (response) {
    console.log(response);
  });
  ```
</CodeGroup>

If successful, this request should return a list of all Organizations (Workspaces) you are part of. It will provide the `name` and `description` for each Organization in the list. The `is_personal` field indicates whether the Organization is a personal one (created automatically upon user account creation). Using a combination of these fields, you should be able to identify the Organization you wish to work with.

Once you have noted down the unique ID (in the `id` field), you are all set to begin to use our API for the correct Workspace.

## What would you like to do next?

<CardGroup cols={3}>
  <Card title="Upload documents" icon="book-open" href="/usecases/document">
    Upload your documents to Petal for cloud processing
  </Card>

  <Card title="Chat with documents" icon="comments" href="/usecases/ai_chat">
    Converse with AI about the contents of your documents
  </Card>

  <Card title="Build AI tables" icon="table-cells" href="/usecases/ai_table">
    Extract information from your documents in this initutive format
  </Card>
</CardGroup>