## Authentication & metadata

URL: https://docs.atlan.com/product/capabilities/build-apps/sdks/application-sdk/api/auth-metadata

> Source system connectivity and metadata operations including credential validation, metadata retrieval, and preflight checks.

<!--vale off-->
Verify source system connection credentials and authentication parameters without performing any data operations. Validates connection string, authentication tokens, SSL certificates, and network accessibility. The exact shape of the request body is defined by the [credentials](https://docs.atlan.com/llms/platform/build-apps/credentials/llms.txt) needed by the app.</>,

 requestBody: {
 contentType: "application/json",
 required: true,
 description: "Source system credentials for the connection to validate. The payload is deserialized into the handler's typed AuthInput and dispatched to handler.test_auth().",
 schema: [
 {
 name: "authType",
 type: "string",
 required: true,
 description: "Source system authentication method",
 enum: ["basic", "oauth", "token"],
 example: "basic"
 },
 {
 name: "host",
 type: "string",
 required: true,
 description: "Source system hostname or IP address",
 example: "localhost"
 },
 {
 name: "port",
 type: "integer",
 required: true,
 description: "Source system port number",
 example: 5432
 },
 {
 name: "username",
 type: "string",
 required: true,
 description: "Source system username for authentication",
 example: "username"
 },
 {
 name: "password",
 type: "string",
 required: true,
 description: "Source system password",
 example: "password"
 },
 {
 name: "database",
 type: "string",
 required: true,
 description: "Target database name or schema identifier for connection scope",
 example: "databasename"
 },
 {
 name: "extra",
 type: "object",
 required: false,
 description: "Extended authentication parameters including SSL certificates, API keys, OAuth tokens, private keys, and database-specific connection options, automatically parsed from JSON string or object format",
 example: {
 "ssl_cert": "-----BEGIN CERTIFICATE-----...",
 "api_key": "sk-1234567890abcdef",
 "oauth_token": "bearer_token_123",
 "ssl_mode": "require"
 }
 }
 ]
 },

 response: {
 status: 200,
 description: "Authentication test completed",
 schema: [
 {
 name: "success",
 type: "boolean",
 required: true,
 description: "Whether authentication was successful",
 example: true
 },
 {
 name: "message",
 type: "string",
 required: true,
 description: "Authentication result message",
 example: "Authentication successful"
 }
 ]
 },

 examples: {
 request: {
 curl: {
 code: `curl -X POST "http://localhost:8000/workflows/v1/auth" \\
 -H "Content-Type: application/json" \\
 -d '{
 "authType": "basic",
 "host": "localhost",
 "port": 5432,
 "username": "username",
 "password": "password",
 "database": "databasename"
 }'`
 },
 python: {
 code: `import requests

response = requests.post(
 "http://localhost:8000/workflows/v1/auth",
 json={
 "authType": "basic",
 "host": "localhost",
 "port": 5432,
 "username": "username",
 "password": "password",
 "database": "databasename"
 }
)
auth_result = response.json()`
 }
 },
 response: {
 "200": `{
 "success": true,
 "message": "Authentication successful"
}`
 }
 }
 },

 {
 id: "fetch-metadata",
 method: "POST",
 path: "/workflows/v1/metadata",
 title: "Fetch metadata",
 description: "Retrieve comprehensive source system structure information including available object hierarchy (databases, schemas, tables), and their relationships. Supports filtering by metadata type and specific object selection for targeted discovery.",

 requestBody: {
 contentType: "application/json",
 required: true,
 description: "Metadata request and source system credentials. The payload is deserialized into the handler's typed MetadataInput and dispatched to handler.fetch_metadata(). The type field (default 'all') controls discovery scope; the database field restricts results to a specific database.",
 schema: [
 {
 name: "type",
 type: "string",
 required: false,
 description: "Scope of metadata discovery operation, defaults to 'all' for comprehensive source system structure retrieval",
 enum: ["database", "schema", "all"],
 defaultValue: "all",
 example: "all"
 },
 {
 name: "database",
 type: "string",
 required: false,
 description: "Target database name to limit metadata discovery scope, omit for all accessible databases",
 example: "specific_database"
 },
 {
 name: "authType",
 type: "string",
 required: true,
 description: "Source system authentication method",
 enum: ["basic", "oauth", "token"],
 example: "basic"
 },
 {
 name: "host",
 type: "string",
 required: true,
 description: "Source system hostname or IP address",
 example: "localhost"
 },
 {
 name: "port",
 type: "integer",
 required: true,
 description: "Source system port number",
 example: 5432
 },
 {
 name: "username",
 type: "string",
 required: true,
 description: "Source system username for authentication",
 example: "username"
 },
 {
 name: "password",
 type: "string",
 required: true,
 description: "Source system password or authentication token",
 example: "password"
 },
 {
 name: "extra",
 type: "object",
 required: false,
 description: "Extended authentication parameters including SSL certificates, API keys, OAuth tokens, private keys, and database-specific connection options, automatically parsed from JSON string or object format",
 example: {
 "ssl_cert": "-----BEGIN CERTIFICATE-----...",
 "api_key": "sk-1234567890abcdef",
 "oauth_token": "bearer_token_123",
 "ssl_mode": "require"
 }
 }
 ]
 },

 response: {
 status: 200,
 description: "Metadata fetched successfully",
 schema: [
 {
 name: "success",
 type: "boolean",
 required: true,
 description: "Whether the operation was successful",
 example: true
 },
 {
 name: "data",
 type: "object",
 required: true,
 description: "Metadata information",
 schema: [
 {
 name: "databases",
 type: "array",
 required: true,
 description: "List of available databases",
 example: ["db1", "db2"]
 },
 {
 name: "schemas",
 type: "object",
 required: true,
 description: "Source system schemas mapping",
 example: {
 "db1": ["public", "private"],
 "db2": ["schema1", "schema2"]
 }
 },
 {
 name: "tables",
 type: "object",
 required: true,
 description: "Source system tables mapping",
 example: {
 "db1.public": ["table1", "table2"],
 "db1.private": ["table3"]
 }
 }
 ]
 }
 ]
 },

 examples: {
 request: {
 curl: {
 code: `curl -X POST "http://localhost:8000/workflows/v1/metadata" \\
 -H "Content-Type: application/json" \\
 -d '{
 "type": "all",
 "database": "specific_database",
 "authType": "basic",
 "host": "localhost",
 "port": 5432,
 "username": "username",
 "password": "password"
 }'`
 },
 python: {
 code: `import requests

response = requests.post(
 "http://localhost:8000/workflows/v1/metadata",
 json={
 "type": "all",
 "database": "specific_database",
 "authType": "basic",
 "host": "localhost",
 "port": 5432,
 "username": "username",
 "password": "password"
 }
)
metadata = response.json()`
 }
 },
 response: {
 "200": `{
 "success": true,
 "data": {
 "databases": ["db1", "db2"],
 "schemas": {
 "db1": ["public", "private"],
 "db2": ["schema1", "schema2"]
 },
 "tables": {
 "db1.public": ["table1", "table2"],
 "db1.private": ["table3"]
 }
 }
}`
 }
 }
 },

 {
 id: "preflight-check",
 method: "POST",
 path: "/workflows/v1/check",
 title: "Preflight check",
 description: "Validate source system connectivity, authentication credentials, and metadata filtering configuration before app execution. Ensures all prerequisites are met and returns detailed success or failure diagnostics.",

 requestBody: {
 contentType: "application/json",
 required: true,
 schema: [
 {
 name: "credentials",
 type: "object",
 required: true,
 description: "Source system connection credentials for preflight validation, including extended authentication parameters",
 schema: [
 {
 name: "authType",
 type: "string",
 required: true,
 description: "Source system authentication method",
 enum: ["basic", "oauth", "token"],
 example: "basic"
 },
 {
 name: "host",
 type: "string",
 required: true,
 description: "Source system hostname or IP address",
 example: "localhost"
 },
 {
 name: "port",
 type: "integer",
 required: true,
 description: "Source system port number",
 example: 5432
 },
 {
 name: "username",
 type: "string",
 required: true,
 description: "Source system username for authentication",
 example: "username"
 },
 {
 name: "password",
 type: "string",
 required: true,
 description: "Source system password or authentication token",
 example: "password"
 },
 {
 name: "database",
 type: "string",
 required: true,
 description: "Target database name or schema identifier for connection scope",
 example: "databasename"
 },
 {
 name: "extra",
 type: "object",
 required: false,
 description: "Extended authentication parameters including SSL certificates, API keys, OAuth tokens, private keys, and database-specific connection options, automatically parsed from JSON string or object format",
 example: {
 "ssl_cert": "-----BEGIN CERTIFICATE-----...",
 "api_key": "sk-1234567890abcdef",
 "oauth_token": "bearer_token_123",
 "ssl_mode": "require"
 }
 }
 ]
 },
 {
 name: "metadata",
 type: "object",
 required: true,
 description: "Metadata filtering configuration for validating source system discovery scope and access permissions",
 schema: [
 {
 name: "include-filter",
 type: "string",
 required: true,
 description: "JSON-encoded regex patterns defining databases and schemas to include in metadata discovery validation",
 example: "{\"^dbengine$\":[\"^public$\",\"^airflow$\"]}"
 },
 {
 name: "exclude-filter",
 type: "string",
 required: true,
 description: "JSON-encoded regex patterns defining databases and schemas to exclude from metadata discovery validation",
 example: "{}"
 },
 {
 name: "temp-table-regex",
 type: "string",
 required: true,
 description: "Regular expression pattern to identify and exclude temporary tables from metadata discovery validation, empty string includes all tables",
 example: ""
 }
 ]
 }
 ]
 },

 response: {
 status: 200,
 description: "Preflight checks completed",
 schema: [
 {
 name: "success",
 type: "boolean",
 required: true,
 description: "Whether preflight checks passed",
 example: true
 },
 {
 name: "data",
 type: "object",
 required: true,
 description: "Preflight check results",
 schema: [
 {
 name: "successMessage",
 type: "string",
 required: true,
 description: "Success message",
 example: "Successfully checked"
 },
 {
 name: "failureMessage",
 type: "string",
 required: true,
 description: "Failure message if checks failed",
 example: ""
 }
 ]
 }
 ]
 },

 examples: {
 request: {
 curl: {
 code: `curl -X POST "http://localhost:8000/workflows/v1/check" \\
 -H "Content-Type: application/json" \\
 -d '{
 "credentials": {
 "authType": "basic",
 "host": "localhost",
 "port": 5432,
 "username": "username",
 "password": "password",
 "database": "databasename"
 },
 "metadata": {
 "include-filter": "{\\"^dbengine$\\":[\\"^public$\\",\\"^airflow$\\"]}",
 "exclude-filter": "{}",
 "temp-table-regex": ""
 }
 }'`
 },
 python: {
 code: `import requests

response = requests.post(
 "http://localhost:8000/workflows/v1/check",
 json={
 "credentials": {
 "authType": "basic",
 "host": "localhost",
 "port": 5432,
 "username": "username",
 "password": "password",
 "database": "databasename"
 },
 "metadata": {
 "include-filter": "{\\"^dbengine$\\":[\\"^public$\\",\\"^airflow$\\"]}",
 "exclude-filter": "{}",
 "temp-table-regex": ""
 }
 }
)
check_result = response.json()`
 }
 },
 response: {
 "200": `{
 "success": true,
 "data": {
 "successMessage": "Successfully checked",
 "failureMessage": ""
 }
}`
 }
 }
 }
 ]}

 errorCodes={[
 {
 code: 400,
 name: "Bad Request",
 description: "Invalid request parameters or malformed JSON payload"
 },
 {
 code: 401,
 name: "Unauthorized",
 description: "Missing or invalid authentication token"
 },
 {
 code: 500,
 name: "Internal Server Error",
 description: "Source system connectivity or authentication error"
 }
 ]}
/>

---