Skip to main content

Credentials

Data credential resources contain encrypted client credentials for accessing data sources and destinations. The credential attributes of these resources are always stored and transmitted in encrypted format. The Nexla encryption library and secret are required to decrypt the credentials for authentication against the external source.

The same data credentials can be used with multiple data sources and destinations.

List All Credentials​

Both Nexla API and Nexla CLI support methods to list all credentials in the authenticated user's account. Details like id, name and type are displayed.

List All Credentails: Request
GET /data_credentials
List All Credentails: Response
[
  {
    "id": 5001,
    "owner": {
      "id": 2,
      "full_name": "Jeff Williams"
    },
    "org": {
      "id": 1,
      "name": "Nexla"
    },
    "access_roles": ["owner"],
    "credentials_type": "s3",
    "credentials_version": "1",
    "credentials_enc": ...,
    "credentials_enc_iv": ...,
    "updated_at": "2016-10-24T22:15:04.000Z",
    "created_at": "2016-10-24T22:15:04.000Z"
  }
]

Show One Credential​

Fetch a specific credential accessible to the authenticated user. The response will contain all the non-secure parts of the credential (like the FTP username) that are helpful to understand the credential context, but will never contain secure sensitive fields (like FTP password).

Show One Credential: Request
GET /data_credentials/{data_credential_id}
Show One Credential: Response
{
  "id": 5001,
  "owner": {
    "id": 2,
    "full_name": "Jeff Williams"
  },
  "org": {
    "id": 1,
    "name": "Nexla"
  },
  "access_roles": ["owner"],
  "name": "Test API",
  "description": null,
  "credentials_type": "rest",
  "credentials_non_secure_data": {
    "auth.type": "NONE",
    "ignore.ssl.cert.validation": false,
    "test.method": "GET",
    "test.content.type": "application/json",
    "jwt.enabled": false,
    "hmac.enabled": false,
    "test.url": "https://demo-api.com/api/info.php?tid=1"
  }
}

Create Credential​

Use the method below to create a credential. This credential can then be associated with any source or destination. Note that you can also create a credential through the methods for creating a source or a destination.

Create A Credential: Request
POST /data_credentials
...Example Request Body
{
  "name": "Test S3 Credentials",
  "credentials_type": "s3",
  "credentials": {
    "credentials_type": "s3",
    "access_key_id": "<AWS Access Key>",
    "secret_key": "<AWS Secret Key>"
  }
}
Create A Credential: Response
{
  "id": 5008,
  "name": "Test S3 Credentials",
  "description": null,
  "owner": {
    "id": 2,
    "full_name": "Jeff Williams",
    "email": "jcw@nexla.com"
  },
  "org": {
    "id": 1,
    "name": "Nexla",
    "email_domain": "nexla.com"
  },
  "access_roles": ["owner"],
  "credentials_type": "s3",
  "credentials_version": "1",
  "credentials_non_secure_data": {
    ...
  }
  "verified_status": null,
  "verified_at": null,
  "updated_at": "2017-06-05T20:24:25.209Z",
  "created_at": "2017-06-05T20:24:25.209Z"
}

Inspect Credential Data​

The endpoints below allow inspection of data that the credentials point to.

These endpoints can be handy when trying to figure out the storage structure and data format of the location a credential points to. For ex, with S3 credential you can inspect the file structure and file content of that S3 location before choosing to create a source/destination based on that credential.

Authenticate Credential​

You can check the validity of a data credentials resource using the /data_credentials/<data_credential_id>/probe or /data_credentials/<data_credential_id>/probe/authenticate endpoint.

A GET call to this endpoint will attempt to authenticate with the remote service using the credential details and return either a 200 response code for success or an error code and message.

Authenticate Credential: Request
GET /data_credentials/{data_credential_id}/probe

Inspect File or Database Type Credential Content Tree​

You can inspect the tree structure in the external source to a particular depth. Note that not all storage types have a natural tree structure.

Inspect File/Database Credential: Request
POST /data_credentials/{data_credential_id}/probe/tree
...
Example Request Body
{
 "region": "us-west-1",
 "bucket": "production-s3-basin",
 "prefix": "events_v2/",
 "depth": 3
}
Inspect File/Database Credential: Response
{
  "status": "ok",
  "connection_type": "s3",
  "output": {
    "events_v2": {
      "2015": {
        "11": {
          "1": {},
          "2": {},
          "3": {}
        },
        "12": {
          "1": {},
          "8": {}
        }
      },
      "2017": {
        "2": {
          "20": {}
        }
      }
    }
  }
}

Inspect File type Credential Content​

Use the endpoint below to get metadata and sample records from a set of files. The POST body must contain path of file starting from the root of the location that data_credential points to.

Inspect File Credential Content: Request
POST /data_credentials/{data_credential_id}/probe/files
...
Example Request Body
{
  "path" : "demo-in.nexla.com",
  "file" : "Demo/Stock.json"
}
Inspect File Credential Content: Response
{
  "status": 200,
  "message": "Ok",
  "output": {
    "format": "json",
    "messages": [
      {
        "Stockname": "sociosqu ad",
        "Total Debt": 8,
        "Return on Assets": 1,
        "Sector": "Mauris",
        "Quick Ration": "1.2"
      },
      {
        "Stockname": "ornare. In",
        "Total Debt": 7,
        "Return on Assets": 3,
        "Sector": "lectus.",
        "Quick Ration": "1.2"
      },
      {
        "Stockname": "nec, diam.",
        "Total Debt": 5,
        "Return on Assets": 5,
        "Sector": "eu",
        "Quick Ration": "1.2"
      }
    ]
  },
  "connection_type": "s3"
}

Inspect Sample Data from Credential​

Use the endpoint below to fetch sample data for a credential. This is useful for viewing sample content of any type of external system before creating a source / destination so that user can decide exactly how to setup the source / destination.

The format of the request body object depends on the data source type. S3 data sources require a path attribute. FTP data sources require only a file attribute, which must contain the full path to an ftp-based file. You can also fetch sample data for third party APIs by setting the payload exactly like the source_config for an equivalent API source.

Inspect Sample Data: Request
POST /data_credentials/{data_credential_id}/probe/sample
...
Example Request Body
{
  "path" : "demo-in.nexla.com",
  "file" : "test/Stock.json"
}
Inspect Sample Data: Response
{
  "status": 200,
  "message": "Ok",
  "output": {
    "response": "\"Store\",\"Upc\"",
    "statusCode": 200,
    "contentType": "text/plain"
  },
  "connection_type": "s3"
}