Using Key Cards

Key cards are plastic cards that unlock doors when presented to a card reader. When you request a card access method in an Access Grant, Seam creates a card credential. Depending on your access control system, you then either encode the credential onto a blank card using a card encoder, or assign it to an existing card by its card number. Key cards work with:

Access control systems — Salto KS, Salto Space, ASSA ABLOY Visionline and Vostio, dormakaba, Brivo, and other ACS platforms that support card-based credentials. Specify entrances with acs_entrance_ids or use space_ids.

Before You Begin

To use key cards, you need:

A Seam API key
A connected ACS that supports card-based credentials
A user identity representing the person who will receive the card
An entrance that supports card access (can_unlock_with_card is true)
For encoding: a compatible card encoder connected to Seam

Step 1: Verify Entrance Support

List the entrances for your ACS and confirm that can_unlock_with_card is true.

const entrances = await seam.acs.entrances.list({
  acs_system_id: 'c359cba2-8ef2-47fc-bee0-1c7c2a886339',
})

const cardEntrances = entrances.filter(
  (e) => e.can_unlock_with_card
)

entrances = seam.acs.entrances.list(
    acs_system_id="c359cba2-8ef2-47fc-bee0-1c7c2a886339"
)

card_entrances = [
    e for e in entrances if e.can_unlock_with_card
]

entrances = seam.acs.entrances.list(
  acs_system_id: "c359cba2-8ef2-47fc-bee0-1c7c2a886339"
)

card_entrances = entrances.select do |e|
  e.can_unlock_with_card
end

$entrances = $seam->acs->entrances->list(
  acs_system_id: "c359cba2-8ef2-47fc-bee0-1c7c2a886339"
);

$cardEntrances = array_filter(
  $entrances,
  fn($e) => $e->can_unlock_with_card
);

var entrances = seam.Acs.Entrances.List(
  acsSystemId: "c359cba2-8ef2-47fc-bee0-1c7c2a886339"
);

var cardEntrances = entrances
  .Where(e => e.CanUnlockWithCard)
  .ToList();

var entrances = seam.acs().entrances().list(
  AcsEntrancesListRequest.builder()
    .acsSystemId("c359cba2-8ef2-47fc-bee0-1c7c2a886339")
    .build()
);

curl -X 'POST' \
  'https://connect.getseam.com/acs/entrances/list' \
  -H "Authorization: Bearer ${SEAM_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
  "acs_system_id": "c359cba2-8ef2-47fc-bee0-1c7c2a886339"
}'

Step 2: Create an Access Grant with a Key Card

Create an Access Grant specifying card as the requested access method mode.

const accessGrant = await seam.accessGrants.create({
  user_identity_id: '22222222-2222-2222-2222-222222222222',
  acs_entrance_ids: ['f74e4879-5991-4e2f-a368-888983dcfbfc'],
  requested_access_methods: [
    { mode: 'card' }
  ],
  starts_at: '2025-07-13T15:00:00.000Z',
  ends_at: '2025-07-16T11:00:00.000Z',
})

access_grant = seam.access_grants.create(
    user_identity_id="22222222-2222-2222-2222-222222222222",
    acs_entrance_ids=["f74e4879-5991-4e2f-a368-888983dcfbfc"],
    requested_access_methods=[{"mode": "card"}],
    starts_at="2025-07-13T15:00:00.000Z",
    ends_at="2025-07-16T11:00:00.000Z",
)

access_grant = seam.access_grants.create(
  user_identity_id: "22222222-2222-2222-2222-222222222222",
  acs_entrance_ids: ["f74e4879-5991-4e2f-a368-888983dcfbfc"],
  requested_access_methods: [{ mode: "card" }],
  starts_at: "2025-07-13T15:00:00.000Z",
  ends_at: "2025-07-16T11:00:00.000Z"
)

$accessGrant = $seam->access_grants->create(
  user_identity_id: "22222222-2222-2222-2222-222222222222",
  acs_entrance_ids: ["f74e4879-5991-4e2f-a368-888983dcfbfc"],
  requested_access_methods: [["mode" => "card"]],
  starts_at: "2025-07-13T15:00:00.000Z",
  ends_at: "2025-07-16T11:00:00.000Z"
);

var accessGrant = seam.AccessGrants.Create(
  userIdentityId: "22222222-2222-2222-2222-222222222222",
  acsEntranceIds: new List<string>
  {
    "f74e4879-5991-4e2f-a368-888983dcfbfc"
  },
  requestedAccessMethods: new List<RequestedAccessMethod>
  {
    new RequestedAccessMethod { Mode = "card" }
  },
  startsAt: "2025-07-13T15:00:00.000Z",
  endsAt: "2025-07-16T11:00:00.000Z"
);

var accessGrant = seam.accessGrants().create(
  AccessGrantsCreateRequest.builder()
    .userIdentityId("22222222-2222-2222-2222-222222222222")
    .acsEntranceIds(List.of(
      "f74e4879-5991-4e2f-a368-888983dcfbfc"
    ))
    .requestedAccessMethods(List.of(
      RequestedAccessMethod.builder()
        .mode("card")
        .build()
    ))
    .startsAt("2025-07-13T15:00:00.000Z")
    .endsAt("2025-07-16T11:00:00.000Z")
    .build()
);

curl -X 'POST' \
  'https://connect.getseam.com/access_grants/create' \
  -H "Authorization: Bearer ${SEAM_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
  "user_identity_id": "22222222-2222-2222-2222-222222222222",
  "acs_entrance_ids": ["f74e4879-5991-4e2f-a368-888983dcfbfc"],
  "requested_access_methods": [{ "mode": "card" }],
  "starts_at": "2025-07-13T15:00:00.000Z",
  "ends_at": "2025-07-16T11:00:00.000Z"
}'

Step 3: Deliver the Key Card

List the access methods for the Access Grant. Two properties tell you how to deliver the card:

is_encoding_required is true: encode the card.
is_assignment_required is true: assign an existing card.

Seam also emits an access_method.card_encoding_required event when a card is ready to encode.

const accessMethods = await seam.accessMethods.list({
  access_grant_id: accessGrant.access_grant_id,
})

const card = accessMethods[0]
console.log(card.is_encoding_required)

access_methods = seam.access_methods.list(
    access_grant_id=access_grant.access_grant_id
)

card = access_methods[0]
print(card.is_encoding_required)

access_methods = seam.access_methods.list(
  access_grant_id: access_grant.access_grant_id
)

card = access_methods[0]
puts card.is_encoding_required

$accessMethods = $seam->access_methods->list(
  access_grant_id: $accessGrant->access_grant_id
);

$card = $accessMethods[0];
echo $card->is_encoding_required;

var accessMethods = seam.AccessMethods.List(
  accessGrantId: accessGrant.AccessGrantId
);

var card = accessMethods[0];
Console.WriteLine(card.IsEncodingRequired);

var accessMethods = seam.accessMethods().list(
  AccessMethodsListRequest.builder()
    .accessGrantId(accessGrant.getAccessGrantId())
    .build()
);

curl -X 'POST' \
  'https://connect.getseam.com/access_methods/list' \
  -H "Authorization: Bearer ${SEAM_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
  "access_grant_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}'

Output:

{
  "access_method_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "display_name": "Key Card",
  "mode": "card",
  "is_issued": false,
  "is_encoding_required": true,
  "is_assignment_required": false,
  ...
}

Encoding Cards

To encode a card, place a blank or reusable card on a card encoder, then call /access_methods/encode with the access method ID and the encoder’s acs_encoder_id. To find the encoder ID, call /acs/encoders/list for your ACS. A site may have several encoders, such as one at each front desk.

const actionAttempt = await seam.accessMethods.encode({
  access_method_id: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
  acs_encoder_id: '33333333-4444-5555-6666-777777777777',
})

action_attempt = seam.access_methods.encode(
    access_method_id="a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    acs_encoder_id="33333333-4444-5555-6666-777777777777",
)

action_attempt = seam.access_methods.encode(
  access_method_id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  acs_encoder_id: "33333333-4444-5555-6666-777777777777"
)

$actionAttempt = $seam->access_methods->encode(
  access_method_id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  acs_encoder_id: "33333333-4444-5555-6666-777777777777"
);

var actionAttempt = seam.AccessMethods.Encode(
  accessMethodId: "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  acsEncoderId: "33333333-4444-5555-6666-777777777777"
);

var actionAttempt = seam.accessMethods().encode(
  AccessMethodsEncodeRequest.builder()
    .accessMethodId("a1b2c3d4-e5f6-7890-abcd-ef1234567890")
    .acsEncoderId("33333333-4444-5555-6666-777777777777")
    .build()
);

curl -X 'POST' \
  'https://connect.getseam.com/access_methods/encode' \
  -H "Authorization: Bearer ${SEAM_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
  "access_method_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "acs_encoder_id": "33333333-4444-5555-6666-777777777777"
}'

Encoding is asynchronous. The request returns an action attempt; confirm that encoding succeeded before you hand the card to your user, in either of these ways:

Poll /action_attempts/get until the action attempt’s status is success.
Listen for the access_method.issued webhook event, or access_method.reissued if you re-encoded a card.

When encoding succeeds, the access method’s is_issued property is true and issued_at records when the card was encoded. If encoding fails, the action attempt’s status is error. Fix the cause and call /access_methods/encode again:

Error type	Cause
`no_card_on_encoder`	No card was on the encoder.
`incompatible_card_format`	The card on the encoder uses an unsupported format.
`uncategorized_error`	Any other encoding error.

You can encode each access method onto only one card. To issue another card, request another card access method. To reuse a physical card, re-encode it with a new access method.

Assigning Cards

If is_assignment_required is true, assign an existing card to the access method by providing its card number. This is common with systems that use pre-registered cards. Use the Seam API to input the card_number for the access method:

const actionAttempt = await seam.accessMethods.assignCard({
  access_method_id: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
  card_number: 'ABCD1234',
})

action_attempt = seam.access_methods.assign_card(
    access_method_id="a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    card_number="ABCD1234",
)

action_attempt = seam.access_methods.assign_card(
  access_method_id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  card_number: "ABCD1234"
)

$actionAttempt = $seam->access_methods->assign_card(
  access_method_id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  card_number: "ABCD1234"
);

var actionAttempt = seam.AccessMethods.AssignCard(
  accessMethodId: "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  cardNumber: "ABCD1234"
);

var actionAttempt = seam.accessMethods().assignCard(
  AccessMethodsAssignCardRequest.builder()
    .accessMethodId("a1b2c3d4-e5f6-7890-abcd-ef1234567890")
    .cardNumber("ABCD1234")
    .build()
);

curl -X 'POST' \
  'https://connect.getseam.com/access_methods/assign_card' \
  -H "Authorization: Bearer ${SEAM_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
  "access_method_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "card_number": "ABCD1234"
}'

When the card is assigned, the access method’s is_issued property is true. Hand the card to your user.

Step 4: See Which Doors the Key Card Covers

An access method can cover multiple doors — for example, if the Access Grant includes several entrances or spaces. To see which doors a key card unlocks, call /access_methods/get_related.

const related = await seam.accessMethods.getRelated({
  access_method_ids: [accessMethod.access_method_id],
})

console.log(related.acs_entrances) // entrances this card unlocks

related = seam.access_methods.get_related(
    access_method_ids=[access_method.access_method_id]
)

print(related.acs_entrances)  # entrances this card unlocks

related = seam.access_methods.get_related(
  access_method_ids: [access_method.access_method_id]
)

puts related.acs_entrances  # entrances this card unlocks

$related = $seam->access_methods->get_related(
  access_method_ids: [$accessMethod->access_method_id]
);

echo json_encode($related->acs_entrances);  // entrances this card unlocks

var related = seam.AccessMethods.GetRelated(
  accessMethodIds: new List<string> { accessMethod.AccessMethodId }
);

// related.AcsEntrances — entrances this card unlocks

var related = seam.accessMethods().getRelated(
  AccessMethodsGetRelatedRequest.builder()
    .accessMethodIds(List.of(accessMethod.getAccessMethodId()))
    .build()
);

curl -X 'POST' \
  'https://connect.getseam.com/access_methods/get_related' \
  -H "Authorization: Bearer ${SEAM_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
  "access_method_ids": ["f47ac10b-58cc-4372-a567-0e02b2c3d479"]
}'

Next Steps

Managing Access Grants — Update or revoke Access Grants, including when to re-encode cards.
Creating an Access Grant — Learn more about specifying devices, entrances, and spaces.
Access Methods API Reference — See all access method properties and endpoints.
Encoders API Reference — See all encoder properties and endpoints.

Getting Started

Use Cases

Core Concepts

Capability Guides

UI Components

Developer Tools

Industry Guides

Device Manufacturer Guidance

Low-Level APIs

Using Key Cards

Before You Begin

Step 1: Verify Entrance Support

Step 2: Create an Access Grant with a Key Card

Step 3: Deliver the Key Card

Encoding Cards

Assigning Cards

Step 4: See Which Doors the Key Card Covers

Next Steps

​Before You Begin

​Step 1: Verify Entrance Support

​Step 2: Create an Access Grant with a Key Card

​Step 3: Deliver the Key Card

​Encoding Cards

​Assigning Cards

​Step 4: See Which Doors the Key Card Covers

​Next Steps

Before You Begin

Step 1: Verify Entrance Support

Step 2: Create an Access Grant with a Key Card

Step 3: Deliver the Key Card

Encoding Cards

Assigning Cards

Step 4: See Which Doors the Key Card Covers

Next Steps