Set up Atlan SDK

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 with at least one persona assigned
• Your Atlan tenant URL (for example, https://tenant.atlan.com)

Install and configure

Python

GitHub repo · Release on PyPI

info

Walk through step-by-step in our intro to custom integration course (30 mins).

Install

Install the SDK

pip install pyatlan

Configure

Option 1—environment variables (recommended)

Set environment variables

export ATLAN_BASE_URL=https://tenant.atlan.com
export ATLAN_API_KEY="<your-api-token>"

main.py

from pyatlan.client.atlan import AtlanClient

client = AtlanClient()

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

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

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

Logging

main.py

import logging
from pyatlan.client.atlan import AtlanClient

logging.basicConfig(level=logging.DEBUG)
client = AtlanClient()

Retries

The SDK retries automatically on 403, 429, and 5xx responses using exponential backoff. The default maximum is 5 retries.

Timeouts

Override default timeouts

from pyatlan.client.atlan import AtlanClient

client = AtlanClient()
client.read_timeout = 1800.0    # 30 minutes (default: 900s)
client.connect_timeout = 60.0   # 1 minute (default: 30s)

Proxies

Configure proxy via environment variables

export HTTPS_PROXY="http://user:[email protected]:1080"
export SSL_CERT_FILE="/path/to/corporate-ca-cert.pem"

Or programmatically:

Programmatic proxy

client = AtlanClient(proxy="http://10.10.1.10:3128")

Async client

Available from v8.0. Mirrors the synchronous API with async/await:

Async client

from pyatlan.client.aio import AsyncAtlanClient

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

Multi-tenant connectivity

Multiple tenants

from pyatlan.client.atlan import AtlanClient

client2 = AtlanClient(base_url="https://tenant2.atlan.com", api_key="...")
Atlan.set_default_client(client2)

Java

GitHub repo · JavaDocs · Release

info

Walk through step-by-step in our intro to custom integration course (30 mins).

Install

Gradle

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

pom.xml

<dependency>
    <groupId>com.atlan</groupId>
    <artifactId>atlan-java</artifactId>
    <version>${atlan.version}</version>
</dependency>

Configure

Option 1—environment variables (recommended)

Set environment variables

export ATLAN_BASE_URL=https://tenant.atlan.com
export ATLAN_API_KEY="<your-api-token>"

AtlanLiveTest.java

import com.atlan.AtlanClient;

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

Option 2—client constructor

AtlanLiveTest.java

import com.atlan.AtlanClient;

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

Logging (Log4j2)

build.gradle

dependencies {
    implementation "com.atlan:atlan-java:+"
    implementation "org.apache.logging.log4j:log4j-core:2.22.0"
    implementation "org.apache.logging.log4j:log4j-slf4j2-impl:2.22.0"
}

Retries

The SDK retries automatically on connection errors, 403, and 500 responses using exponential backoff with jitter (500ms–5s per retry, default maximum 3 retries).

Configure the maximum:

Configure max retries

try (AtlanClient client = new AtlanClient()) {
    client.setMaxNetworkRetries(5);
}

Timeouts

Default is 80 seconds. Override with milliseconds:

Configure timeout

try (AtlanClient client = new AtlanClient()) {
    client.setReadTimeout(120_000);  // 2 minutes
}

Kotlin

GitHub repo · Release

Kotlin uses the Java SDK from Maven Central.

Install

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)

Set environment variables

export ATLAN_BASE_URL=https://tenant.atlan.com
export ATLAN_API_KEY="<your-api-token>"

AtlanLiveTest.kt

import com.atlan.AtlanClient

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

Option 2—client constructor

AtlanLiveTest.kt

import com.atlan.AtlanClient

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

Scala

GitHub repo · Release

Scala uses the Java SDK from Maven Central.

Install

build.sbt

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)

Set environment variables

export ATLAN_BASE_URL=https://tenant.atlan.com
export ATLAN_API_KEY="<your-api-token>"

AtlanLiveTest.scala

import com.atlan.AtlanClient
import scala.util.Using

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

Option 2—client constructor

AtlanLiveTest.scala

import com.atlan.AtlanClient
import scala.util.Using

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

Clojure

GitHub repo · Release

Clojure uses the Java SDK from Maven Central.

Install

deps.edn

{
  :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)

Set environment variables

export ATLAN_BASE_URL=https://tenant.atlan.com
export ATLAN_API_KEY="<your-api-token>"

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

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

Pre-release

The Go SDK is experimental. Breaking changes may occur without notice. Feedback is welcome—see the GitHub repo.

Install

Install the Go SDK

go get github.com/atlanhq/atlan-go

Configure

Option 1—environment variables (recommended)

Set environment variables

export ATLAN_BASE_URL=https://tenant.atlan.com
export ATLAN_API_KEY="<your-api-token>"

main.go

package main

import "github.com/atlanhq/atlan-go/atlan/assets"

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

Option 2—client constructor

main.go

package main

import "github.com/atlanhq/atlan-go/atlan/assets"

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

CLI

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.

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

Install

Homebrew (recommended)

brew tap atlanhq/atlan
brew install atlan

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

macOS (Apple silicon)

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)

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

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

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:

.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):

.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 (45 mins).

No installation required. Use dbt's meta field to enrich metadata from your dbt project directly into Atlan.

How it works

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

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.

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 in Atlan to receive event payloads.
2. Implement an event handler using the Python or Java SDK.

See event handling how-tos 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. 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—we'd love to understand why.