## Set up Atlan SDK

URL: https://docs.atlan.com/product/capabilities/build-apps/sdks/python/how-tos/set-up-sdk

> Install and configure the Atlan Python SDK (pyatlan) and other integration approaches for building metadata workflows.

Choose your preferred integration approach and follow the steps below. All SDK-based approaches use the same two environment variables for authentication.

## Prerequisites

- An Atlan [API token](https://ask.atlan.com/hc/en-us/articles/8312649180049) with at least one persona assigned
- Your Atlan tenant URL (for example, `https://tenant.atlan.com`)

## Install and configure

### Python

[GitHub repo](https://github.com/atlanhq/atlan-python) · [Release on PyPI](https://pypi.org/project/pyatlan/)

:::info
Walk through step-by-step in our [intro to custom integration course](https://university.atlan.com/training/e12dcbe2-0ad9-11ee-8e89-06e5f0a66511/overview) (30 mins).
:::

### Install

```console title="Install the SDK"
pip install pyatlan
```

### Configure

**Option 1—environment variables (recommended)**

```console title="Set environment variables"
export ATLAN_BASE_URL=https://tenant.atlan.com
export ATLAN_API_KEY="<your-api-token>"
```

```python showLineNumbers title="main.py"
from pyatlan.client.atlan import AtlanClient

client = AtlanClient()
```

You can also authenticate with OAuth credentials instead of an API token:

```console title="OAuth environment variables"
export ATLAN_BASE_URL=https://tenant.atlan.com
export ATLAN_OAUTH_CLIENT_ID=<client-id>
export ATLAN_OAUTH_CLIENT_SECRET=<client-secret>
```

**Option 2—client constructor**

```python showLineNumbers title="main.py"
from pyatlan.client.atlan import AtlanClient

# Using API token

client = AtlanClient(
 base_url="https://tenant.atlan.com",
 api_key="<your-api-token>"
)

# Using OAuth credentials

client = AtlanClient(
 base_url="https://tenant.atlan.com",
 oauth_client_id="<client-id>",
 oauth_client_secret="<client-secret>",
)
```

:::warning
Avoid hardcoding your API token in source files—you may accidentally commit it to a public repository.
:::

> *Advanced configuration—logging, retries, timeouts, proxies, async — see full content on the documentation site.*

### Java

[GitHub repo](https://github.com/atlanhq/atlan-java) · [JavaDocs](https://atlanhq.github.io/atlan-java/) · [Release](https://central.sonatype.com/artifact/com.atlan/atlan-java)

:::info
Walk through step-by-step in our [intro to custom integration course](https://university.atlan.com/training/e12dcbe2-0ad9-11ee-8e89-06e5f0a66511/overview) (30 mins).
:::

### Install

```groovy title="build.gradle"
repositories {
 mavenCentral()
}

dependencies {
 implementation "com.atlan:atlan-java:+" // (1)
 testRuntimeOnly 'ch.qos.logback:logback-classic:1.2.11' // (2)
}
```

1. Use `+` for the latest version, or pin to a specific version.
2. Logback binds slf4j to stdout at INFO level or above.

### Maven

```xml title="pom.xml"
<dependency>
 <groupId>com.atlan</groupId>
 <artifactId>atlan-java</artifactId>
 <version>${atlan.version}</version>
</dependency>
```

### Configure

**Option 1—environment variables (recommended)**

```console title="Set environment variables"
export ATLAN_BASE_URL=https://tenant.atlan.com
export ATLAN_API_KEY="<your-api-token>"
```

```java showLineNumbers title="AtlanLiveTest.java"

try (AtlanClient client = new AtlanClient()) {
 // client is ready
}
```

**Option 2—client constructor**

```java showLineNumbers title="AtlanLiveTest.java"

try (AtlanClient client = new AtlanClient("https://tenant.atlan.com", "<your-api-token>")) {
 // client is ready
}
```

:::warning
Avoid hardcoding your API token in source files—you may accidentally commit it to a public repository.
:::

> *Advanced configuration—logging, retries, timeouts — see full content on the documentation site.*

### Kotlin

[GitHub repo](https://github.com/atlanhq/atlan-java) · [Release](https://central.sonatype.com/artifact/com.atlan/atlan-java)

Kotlin uses the Java SDK from Maven Central.

### Install

```kotlin title="build.gradle.kts"
repositories {
 mavenCentral()
}

dependencies {
 implementation("com.atlan:atlan-java:+") // (1)
 implementation("io.github.microutils:kotlin-logging-jvm:3.0.5")
 implementation("org.slf4j:slf4j-simple:2.0.7")
}
```

1. Use `+` for the latest version, or pin to a specific version.

### Configure

**Option 1—environment variables (recommended)**

```console title="Set environment variables"
export ATLAN_BASE_URL=https://tenant.atlan.com
export ATLAN_API_KEY="<your-api-token>"
```

```kotlin showLineNumbers title="AtlanLiveTest.kt"

fun main() {
 AtlanClient().use { client ->
 // client is ready
 }
}
```

**Option 2—client constructor**

```kotlin showLineNumbers title="AtlanLiveTest.kt"

fun main() {
 AtlanClient("https://tenant.atlan.com", "<your-api-token>").use { client ->
 // client is ready
 }
}
```

### Scala

[GitHub repo](https://github.com/atlanhq/atlan-java) · [Release](https://central.sonatype.com/artifact/com.atlan/atlan-java)

Scala uses the Java SDK from Maven Central.

### Install

```scala title="build.sbt" showLineNumbers
name := "Main"
version := "1.0"
scalaVersion := "2.13.14"

lazy val main = project
 .in(file("."))
 .settings(
 name := "Main",
 libraryDependencies ++= Seq(
 "com.atlan" % "atlan-java" % "+", // (1)
 "com.typesafe.scala-logging" %% "scala-logging" % "3.9.5"
 )
 )
```

1. Replace `+` with the specific version shown in the badge above.

### Configure

**Option 1—environment variables (recommended)**

```console title="Set environment variables"
export ATLAN_BASE_URL=https://tenant.atlan.com
export ATLAN_API_KEY="<your-api-token>"
```

```scala showLineNumbers title="AtlanLiveTest.scala"

object Main extends App {
 Using(new AtlanClient()) { client =>
 // client is ready
 }
}
```

**Option 2—client constructor**

```scala showLineNumbers title="AtlanLiveTest.scala"

object Main extends App {
 Using(new AtlanClient("https://tenant.atlan.com", "<your-api-token>")) { client =>
 // client is ready
 }
}
```

### Clojure

[GitHub repo](https://github.com/atlanhq/atlan-java) · [Release](https://central.sonatype.com/artifact/com.atlan/atlan-java)

Clojure uses the Java SDK from Maven Central.

### Install

```clojure title="deps.edn" showLineNumbers
{
 :aliases
 {
 :run {:ns-default my.proj
 :main-opts ["-m" "my.proj"]
 :jvm-opts ["-Dclojure.tools.logging.factory=clojure.tools.logging.impl/slf4j-factory"]
 :deps {
 com.atlan/atlan-java {:mvn/version "+"} ;; (1)
 org.clojure/tools.logging {:mvn/version "1.3.0"}
 org.slf4j/slf4j-simple {:mvn/version "2.0.7"}
 }
 }
 }}
```

1. Replace `+` with the specific version shown in the badge above.

### Configure

**Option 1—environment variables (recommended)**

```console title="Set environment variables"
export ATLAN_BASE_URL=https://tenant.atlan.com
export ATLAN_API_KEY="<your-api-token>"
```

```clojure showLineNumbers title="src/my/proj.clj"
(ns my.proj
 (:import com.atlan.AtlanClient)
 (:require [clojure.tools.logging :as logger]))

(defn -main [& args]
 (with-open [client (AtlanClient.)]
 (logger/info "Client ready")))
```

**Option 2—client constructor**

```clojure showLineNumbers title="src/my/proj.clj"
(defn -main [& args]
 (with-open [client (AtlanClient. "https://tenant.atlan.com" "<your-api-token>")]
 (logger/info "Client ready")))
```

### Go

[GitHub repo](https://github.com/atlanhq/atlan-go)

:::warning[Pre-release]
The Go SDK is experimental. Breaking changes may occur without notice. Feedback is welcome—see the [GitHub repo](https://github.com/atlanhq/atlan-go).
:::

### Install

```console title="Install the Go SDK"
go get github.com/atlanhq/atlan-go
```

### Configure

**Option 1—environment variables (recommended)**

```console title="Set environment variables"
export ATLAN_BASE_URL=https://tenant.atlan.com
export ATLAN_API_KEY="<your-api-token>"
```

```go showLineNumbers title="main.go"
package main

func main() {
 client := assets.NewContext()
 // client is ready
}
```

**Option 2—client constructor**

```go showLineNumbers title="main.go"
package main

func main() {
 client := assets.NewContext(
 assets.WithBaseURL("https://tenant.atlan.com"),
 assets.WithAPIKey("<your-api-token>"),
 )
 // client is ready
}
```

### CLI

:::warning[Closed preview]
The Atlan CLI is in closed preview. Contact your Atlan Customer Success Manager to request access. Installation is subject to [Product Release Stage terms](https://ask.atlan.com/hc/en-us/articles/7354918064783-Product-release-stages#h_01HW5DQK658B49YE5FM11RQMZ4).
:::

Use the Atlan CLI to manage data contracts and sync metadata for a limited set of asset types.

### Install

```shell
brew tap atlanhq/atlan
brew install atlan
```

Homebrew keeps the CLI up-to-date with `brew upgrade atlan`.

### macOS (Apple silicon)

```shell
curl -o atlan.tgz -L https://github.com/atlanhq/atlan-cli-releases/releases/latest/download/atlan_Darwin_arm64.tar.gz
tar xf atlan.tgz
```

### macOS (Intel)

```shell
curl -o atlan.tgz -L https://github.com/atlanhq/atlan-cli-releases/releases/latest/download/atlan_Darwin_amd64.tar.gz
tar xf atlan.tgz
```

### Linux

```shell
curl -o atlan.tgz -L https://github.com/atlanhq/atlan-cli-releases/releases/latest/download/atlan_Linux_amd64.tar.gz
tar -zxf atlan.tgz
```

### Windows

```shell
curl -o atlan.zip -L https://github.com/atlanhq/atlan-cli-releases/releases/latest/download/atlan_Windows_amd64.zip
unzip atlan.zip
```

### Configure

Create `.atlan/config.yaml` in your home directory:

```yaml showLineNumbers title=".atlan/config.yaml"
atlan_api_key: "<your-api-token>" # (1)
atlan_base_url: https://tenant.atlan.com # (2)
log:
 enabled: false # (3)
 level: info
```

1. An API token with access to your assets.
2. The base URL of your tenant, including `https://`.
3. Set to `true` to enable verbose logging.

Alternatively, set `ATLAN_API_KEY` as an environment variable—it takes precedence over the config file.

**Define data sources** (required for data contract operations):

```yaml title=".atlan/config.yaml"
data_source snowflake: # (1)
 type: snowflake
 connection:
 name: snowflake-prod
 qualified_name: "default/snowflake/1234567890"
 database: db
 schema: analytics
```

1. Each data source definition starts with `data_source` followed by a unique reference name.

### dbt

:::info
See it in action in our [automated enrichment course](https://university.atlan.com/training/e12c0834-0ad9-11ee-8e89-06e5f0a66511/overview) (45 mins).
:::

No installation required. Use [dbt's `meta` field](https://docs.getdbt.com/reference/resource-configs/meta) to enrich metadata from your dbt project directly into Atlan.

### How it works

Add an `atlan` block inside `meta` on any model or column:

```yaml showLineNumbers title="models/schema.yml"
version: 2
models:
 - name: customers
 description: >-
 This table has basic information about a customer.
 meta:
 atlan:
 attributes: # (1)
 certificateStatus: DRAFT
 ownerUsers: ["bryan", "ashwin"]
 classifications: # (2)
 - typeName: "ipubxAPPb0zRcNU1Gkjs9b"
 propagate: true
 removePropagationsOnEntityDelete: true
 restrictPropagationThroughLineage: true
 restrictPropagationThroughHierarchy: false
 columns:
 - name: customer_id
 description: Unique identifier for a customer.
 - name: total_order_amount
 meta:
 atlan: # (3)
 attributes:
 certificateStatus: DRAFT
 ownerUsers: ["ravi"]
```

1. Set asset attributes such as certificates, announcements, and owners inside `attributes`.
2. Apply classifications inside `classifications`.
3. The same `meta` structure applies to columns within a model.

For field-by-field examples, look for the **dbt** tab in the [asset how-tos](https://docs.atlan.com/llms/platform/python/how-tos/llms.txt).

### Events

Atlan emits events when metadata changes—asset created, updated, tagged, lineage added, and more. Tap into these in a push-based model to take action the moment they occur.

### How it works

1. Set up a [webhook](https://ask.atlan.com/hc/en-us/articles/7145739770511) in Atlan to receive event payloads.
2. Implement an event handler using the Python or Java SDK.

See [event handling how-tos](https://docs.atlan.com/llms/platform/python/how-tos/llms.txt) for implementation details, including AWS Lambda deployment.

### Raw REST API

:::warning
Direct REST API usage requires deep knowledge of Atlan's payload structures, enumeration values, and HTTP conventions. We strongly recommend using an SDK instead.
:::

All SDKs communicate through the same REST API and encode the best practices for you. If you want to use the SDKs, start with the Python or Java tabs above.

### Postman

For initial experimentation, use [Postman](https://getpostman.com). Look for the **Raw REST API** tab on any how-to page for the endpoint URL and example payload.

### OpenAPI spec

We don't publish a usable OpenAPI spec. We attempted generated clients but found that generators dropped significant portions of payload data and produced cumbersome object hierarchies. We maintain the SDKs directly instead.

If you use raw REST APIs rather than an SDK, [share your use case](https://docs.google.com/forms/d/e/1FAIpQLSefT0YDg3IOTTP30YKQjwPaWCaKmBKyrGFdHFgUY-lEfdz2NA/viewform?usp=sf_link)—we'd love to understand why.

---